3. OpenAPI 规范详解：OpenAPI 3.0 核心结构、路径与操作定义、请求/响应模型设计

OpenAPI 规范（原 Swagger 规范）是业界最广泛采用的 RESTful API 契约描述标准。OpenAPI 3.0 版本在数据结构、可复用性、安全定义和链接（Links）方面进行了重大升级，成为微服务间通信治理的核心工具。本章将深入剖析 OpenAPI 3.0 的顶层结构、路径与操作定义模式，以及请求/响应模型的精确设计方法。

3.1 OpenAPI 3.0 核心结构

一个合法的 OpenAPI 3.0 文档是一个符合 JSON Schema 的 JSON 或 YAML 文件。其顶层对象包含以下关键字段，构成了 API 契约的骨架：

3.2 路径与操作定义

Paths Object 是 API 契约的核心，它将 HTTP 方法（GET、POST、PUT、DELETE、PATCH 等）与具体的业务逻辑端点绑定。每个路径下可以定义一个或多个操作（Operation Object）。

3.2.1 路径定义规范

• 路径模板： 使用花括号 {} 表示路径参数，如 /users/{userId}。
• 操作对象： 包含 operationId（唯一标识）、summary、description、parameters、requestBody、responses 等。
• 参数来源： 支持 path、query、header、cookie 四种位置。

3.2.2 操作定义示例

以下是一个标准的用户查询与创建路径定义，展示了路径参数、查询参数和请求体的组合使用：

paths:
  /users:
    get:
      operationId: listUsers
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
    post:
      operationId: createUser
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: 请求参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /users/{userId}:
    get:
      operationId: getUserById
      summary: 根据 ID 获取用户详情
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功返回用户对象
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在

3.3 请求/响应模型设计

请求与响应模型的设计直接决定了 API 契约的严谨性和可消费性。OpenAPI 3.0 通过 requestBody 和 responses 对象，结合 components/schemas 实现精确的数据契约。

3.3.1 请求体（requestBody）设计

与 Swagger 2.0 不同，OpenAPI 3.0 将 body 参数提升为独立的 requestBody 对象，支持多 Content-Type 和更清晰的描述。

• required： 布尔值，标记请求体是否必须。
• content： 映射表，键为 MIME 类型（如 application/json、multipart/form-data），值为 Media Type Object。
• Media Type Object： 包含 schema（数据模型）和 example（示例值）。

3.3.2 响应（responses）设计

每个操作必须至少定义一个成功响应（通常为 200、201 或 204），并建议覆盖常见的错误响应。

3.3.3 Schema 复用与组合

通过 $ref 引用 components/schemas 中的模型，是实现契约一致性的关键手段。OpenAPI 3.0 支持 JSON Schema 的 allOf、oneOf、anyOf 组合关键字，用于构建复杂的继承或多态模型。

components:
  schemas:
    # 基础用户模型
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        displayName:
          type: string
        createdAt:
          type: string
          format: date-time
    # 创建用户请求模型（继承 User 但不包含 id）
    CreateUserRequest:
      type: object
      required:
        - email
        - displayName
      properties:
        email:
          type: string
          format: email
        displayName:
          type: string
        password:
          type: string
          minLength: 8
    # 标准错误响应模型
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              reason:
                type: string
    # 用户列表响应模型
    UserList:
      type: object
      required:
        - items
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total:
          type: integer

3.4 契约治理与工具链集成

OpenAPI 3.0 规范本身只是契约的“语法”，真正的治理价值体现在工具链的集成与自动化校验中。以下是在服务间通信治理中必须建立的关键实践：

1. 契约存储与版本管理： 将 OpenAPI 文件纳入 Git 仓库，与微服务代码同源管理。每次 API 变更必须经过 Code Review。
2. 自动化校验： 在 CI 流水线中集成 spectral 或 vacuum 等 linter，强制执行组织级规则（如所有响应必须包含 description、禁止使用 anyOf 等）。
3. 契约测试： 使用 dredd 或 pact 验证服务实现是否与 OpenAPI 契约一致，防止服务端“过度暴露”或“遗漏字段”。
4. 文档与 SDK 生成： 利用 redoc、swagger-ui 生成交互式文档；使用 openapi-generator 生成类型安全的客户端 SDK。