OpenAPI规范 – Swagger 规范

OpenAPI（以前叫 Swagger 规范）是一个用于描述 RESTful API 的标准格式。

它定义了 API 的：

• 端点（路径）
• 请求/响应格式
• 参数
• 认证方式
• 数据结构

最新版本是 OpenAPI 3.0（由 OpenAPI Initiative 维护）。

示例 OpenAPI 规范（YAML 格式）

openapi: 3.0.0
info:
  title: 示例 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: 张三

个 openapi.yaml 文件描述了一个 API 接口 /users，用于获取用户列表。