测试：YAML & OpenAPI（Swagger）

YAML

YAML（Yet Another Markup Language）是一种数据序列化格式，通常被用来配置文件。它易于阅读，并且以数据结构为中心。YAML文件通常以`.yaml`或`.yml`为扩展名。

下面是一个YAML文件的简单示例：定义了一个人的基本信息，包括姓名、年龄、婚姻状态以及孩子的列表。

# 这是一个注释
name: John Doe
age: 30
married: true
children:
  - name: Jimmy
    age: 5
  - name: Jenny
    age: 7

OpenAPI

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

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

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

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

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

OpenAPI接口定义的YAML

OpenAPI规范允许以YAML格式定义接口的信息，包括端点、操作、参数、响应等。

一个简单的OpenAPI接口定义的YAML示例：定义了一个名为“Sample API”的API，该API有一个端点（/users）用于获取用户列表。定义了请求参数、响应以及用户的数据结构。

openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
  description: A sample API for demonstration purposes.
  termsOfService: https://example.com/terms
  contact:
    name: API Support
    email: [email protected]
    url: https://example.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://api.example.com/v1
paths:
  /users:
    get:
      tags:
        - Users
      summary: Retrieve a list of users.
      description: Returns a list of registered users.
      parameters:
        - name: limit
          in: query
          description: The number of users to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: Bad request.
        '500':
          description: Internal server error.
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: John Doe
        email:
          type: string
          example:[email protected]

Open API 的官方文档

Open API 的官方文档是由 OpenAPI Initiative（OAI）维护的。可以在 OpenAPI Initiative 的官方网站找到 Open API 的规范文档。这些文档详细介绍了 Open API 的各个方面，包括规范的核心组件、格式以及如何使用它来描述 RESTful 服务。

参考：

OpenAPI 代码生成文档：GitHub - OpenAPITools/openapi-generator: OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
OpenAPI 官方博客：https://www.openapis.org/blog

实现和工具

OpenAPI 还有一些流行的实现和工具，如 Swagger UI、Postman、Springfox 等，它们提供了 OpenAPI 规范的支持，并可以帮助开发者更轻松地创建、测试和文档化 API。这些工具和库通常也会附带相应的官方文档。