使用yaml管理api接口之OpenAPI规范

什么是OpenAPI规范

官方文档：https://spec.openapis.org/
swagger官方文档：https://swagger.io/specification/
apifox中文版：https://openapi.apifox.cn/

OpenAPI（之前称为Swagger）是一种规范，用于描述、消费和可视化 RESTful web 服务。它提供了一种可读性强且易于理解的格式，可以让人和机器都能读懂。OpenAPI 规范允许开发人员设计、构建、记录和使用 RESTful 服务，同时还提供了可视化界面，方便测试和交互。

OpenAPI 是规范化描述 API 领域应用最广泛的行业标准，由 OpenAPI Initiative(OAI) 定义并维护，同时也是 Linux 基金会下的一个开源项目。通常我们所说的 OpenAPI 全称应该是 OpenAPI Specification(OpenAPI 规范，简称 OSA)，它使用规定的格式来描述 HTTP RESTful API 的定义，以此来规范 RESTful 服务开发过程。

OpenAPI 规范可以采用 YAML 或 JSON 格式编写。YAML 格式更易于阅读和编写，而 JSON 格式则更适合机器解析。

OpenAPI 规范的一个优点是它可以让开发人员、API 用户和自动化工具轻松地理解和交互 API。这使得 API 的文档化、测试和集成变得更加简单。许多工具和库（如 Swagger UI、Postman、Springfox 等）都支持 OpenAPI 规范，可以自动生成 API 文档和可视化界面。

简单来说，OpenAPI 就是用来定义 HTTP 接口文档的一种规范，大家都按照同一套规范来编写接口文档，能够极大的减少沟通成本。

OpenAPI 规范定义了几个核心组件，包括：

• 概述（Info）：提供有关 API 的基本信息，例如标题、描述、版本、许可协议等。
• 服务器（Servers）：定义 API 服务的地址和基础路径。
• 路径（Paths）：描述 API 的端点（URL）和相关的请求方法（GET、POST、PUT 等）。
• 操作（Operations）：定义每个端点的具体操作，包括请求和响应的详细信息。
• 参数（Parameters）：描述请求参数，例如查询字符串、请求体等。
• 响应（Responses）：定义可能的响应状态码以及相应的消息和格式。
• 数据模型（Components）：提供可重用的数据模型，例如请求和响应的结构。

规范扩展

尽管 OpenAPI Specification 尝试包含大部分的使用场景，在需要时仍然可以通过附加数据来扩展此规范。

此扩展属性被设计为总是以 “x-” 为前缀的模式字段。

常用数据结构总结

tags: 功能类似的 API 操作归类到同一个标签下

定义：

• tags: 是 OpenAPI 规范中用于对 API 操作（如 GET、POST 等）进行分类的字段。
• 它是一个数组，可以包含多个标签（tag），用于将相关的 API 操作分组。

作用：

• API 分组：将功能类似的 API 操作归类到同一个标签下，便于在 API 文档中查找和管理。
• 文档生成：API 文档生成工具（如 Swagger UI）会根据 tags: 对 API 进行分组展示。

$ref 引用其他部分的定义

在 OpenAPI 3.0.0 规范中，$ref 是一个关键字，用于引用其他部分的定义。它的作用是避免重复定义，提高代码的复用性和可维护性。

$ref 用于引用 OpenAPI 文档中已经定义的内容。通过 $ref，可以将重复的部分提取出来，放到 components 中定义，然后在需要的地方引用。

优点：

• 复用性：将公共部分（如请求体、响应体）提取到 components 中，可以在多个地方复用。
• 可维护性：如果需要修改某个定义，只需修改 components 中的部分，所有引用该定义的地方都会自动更新。
• 简洁性：避免重复定义，使 OpenAPI 文档更加简洁。

requestBody 请求体

在 OpenAPI 3.0.0 规范中，requestBody 是一个关键字，用于定义 API 请求的请求体。

requestBody 用于指定以下内容：

• 请求体的格式（如 application/json、multipart/form-data 等）。
• 请求体的数据结构（如 JSON 对象、表单数据等）。
• 请求体是否必填（通过 required 字段）。

parameters 请求参数

在 OpenAPI 3.0.0 规范中，parameters 是一个关键字，用于定义 API 请求中的参数。这些参数可以出现在 URL 路径、查询字符串、请求头或 Cookie 中。

parameters 用于指定以下内容：

• 参数的位置：参数可以出现在路径（path）、查询字符串（query）、请求头（header）或 Cookie（cookie）中。
• 参数的类型：如字符串、整数、布尔值等。
• 参数是否必填：通过 required 字段指定。
• 参数的描述：帮助开发者理解参数的用途。

{} 路径变量

在 OpenAPI 3.0.0 中，路径变量（Path Parameters）通过 {} 来表示，并在 parameters 中定义其详细信息。

parameters：

• required: true：路径变量默认是必填的。

在 OpenAPI 规范中，路径参数必须明确声明，并定义其位置、类型和必填性。

否则报错Declared path parameter {xxx needs to be defined as a path parameter in path or operation level

使用**allOf** data 字段合并

使用**allOf** 复用 CommonResponse 结构，同时单独处理 data 字段

CommonResponse 定义

components:
  schemas:
    CommonResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
          description: 返回码
        msg:
          type: string
          example: "success"
          description: 返回信息
        requestID:
          type: string
          example: "12345"
          description: 请求ID

1. allOf：
   • 使用 allOf 将 CommonResponse 和自定义的 data 字段合并。
   • allOf 允许组合多个模式（schemas），确保最终的响应结构包含 CommonResponse 和 data 字段。
2. CommonResponse：
   • 定义了公共字段 code、msg 和 requestID，可以在多个接口中复用。
3. data 字段：
   • 在 200 响应中，单独定义 data 字段及其结构。
   • data 字段的类型和内容可以根据接口需求自定义。

paths:
  /example:
    get:
      summary: 示例接口
      description: 这是一个示例接口。
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/CommonResponse"
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          exampleField:
                            type: string
                            example: "exampleValue"

示例响应

根据上述 YAML，生成的响应示例如下：

{
  "code": 0,
  "msg": "success",
  "requestID": "12345",
  "data": {
    "exampleField": "exampleValue"
  }
}

总结

• 使用 allOf 复用 CommonResponse，同时单独定义 data 字段。
• 这种方式可以避免重复定义公共字段，同时保持响应结构的灵活性。

常见问题

同一个路径不能定义多次

在 OpenAPI 规范中，同一个路径不能定义多次，即使它们的 HTTP 方法（如 GET 和 POST）不同。

为了解决这个问题，你需要将 GET 和 POST 操作合并到同一个路径下。

报错：should start with /

在 OpenAPI 规范中，路径（path）的定义必须以斜杠 / 开头。这是 OpenAPI 规范的基本要求，所有路径都必须遵循这一规则。

根据 OpenAPI YAML 文件生成界面

Stoplight 是一个用于 API 设计、文档、测试和治理 的综合性平台。它提供了一套工具和功能，帮助开发团队更高效地设计、发布和维护 API。Stoplight 的核心目标是简化 API 开发流程，确保 API 的一致性、可维护性和易用性。

Stoplight CLI

• 命令行工具，用于在本地或 CI/CD 环境中验证、测试和生成 API 文档。

• 强大的文档功能：生成的文档美观、交互式，用户体验好。

https://unpkg.com/@stoplight/elements/web-components.min.js 是 Stoplight Elements 的 Web Components 版本，它是一个用于生成和展示 API 文档 的 JavaScript 库。Stoplight Elements 是 Stoplight 平台的一部分，专注于提供美观、交互式的 API 文档。

Stoplight Elements 是什么？

github：https://github.com/stoplightio/elements

Stoplight Elements 是一个开源的 API 文档工具，基于 React 或 Web Components 构建。它可以将 OpenAPI 规范（Swagger）文件转换为交互式的 API 文档页面。主要特点包括：

1. 美观的 UI：
   • 提供现代化的、响应式的用户界面。
   • 支持深色模式和浅色模式。
2. 交互式文档：
   • 支持在文档中直接测试 API 端点。
   • 提供请求示例和响应示例。
3. 基于 OpenAPI：
   • 完全支持 OpenAPI 3.0 和 Swagger 2.0 规范。
4. 多种集成方式：
   • 支持 React 组件和 Web Components，方便集成到任何 Web 应用中。
5. 可定制性：
   • 提供丰富的配置选项，可以根据需求定制文档的外观和功能。

Stoplight Elements 是 Stoplight 平台的一部分，但也可以独立使用。Stoplight 平台提供了更全面的 API 设计、文档、测试和治理功能，而 Stoplight Elements 主要用于生成和展示 API 文档。

• Stoplight 平台：
  • 提供 API 设计工具、文档托管、测试和治理功能。
  • 适合团队协作和 API 全生命周期管理。
• Stoplight Elements：
  • 专注于生成美观、交互式的 API 文档。
  • 适合集成到现有项目或独立使用。

总结

• @stoplight/elements/web-components.min.js 是 Stoplight Elements 的 Web Components 版本，用于在 HTML 中渲染 API 文档。
• 它基于 OpenAPI 规范，提供美观、交互式的文档界面。
• 通过简单的配置，可以快速集成到任何 Web 项目中。

使用

OpenAPI工具列表

https://openapi.tools/