3. OpenAPI 规范回顾：OpenAPI 3.0/3.1 核心结构、路径、组件、Schema 定义

在迁移后的数据契约冒烟检查中，OpenAPI 规范是契约的“语法骨架”。无论是 3.0 还是 3.1 版本，其核心结构都围绕 路径（Paths）、组件（Components） 和 Schema 定义 展开。理解这些核心要素，是编写冒烟检查脚本、定位契约断裂点的前提。

3.1 核心结构：从文档根到操作

一个标准的 OpenAPI 文档是一个 JSON 或 YAML 对象，其顶层字段定义了 API 的全局信息、服务器、路径和组件。下表对比了 3.0 与 3.1 版本在顶层结构上的关键差异：

3.2 路径（Paths）与操作（Operations）

路径是 API 的端点集合，每个路径下可定义多个 HTTP 方法（操作）。路径定义中包含了请求参数、请求体和响应对象。以下是一个典型的路径定义示例：

paths:
  /users/{userId}:
    get:
      summary: 获取用户信息
      operationId: getUserById
      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: 用户不存在

在冒烟检查中，路径部分需要验证以下三个维度：

• 路径一致性： 迁移后的路径模板是否与旧契约一致？参数占位符（如 {userId}）是否被错误地硬编码？
• 操作完整性： 每个路径下的 HTTP 方法是否完整？是否遗漏了 PATCH 或 DELETE 等操作？
• 响应状态码： 是否覆盖了所有预期的状态码（如 200、201、400、404、500）？缺少状态码定义会导致客户端 SDK 生成失败。

3.3 组件（Components）与引用机制

组件是 OpenAPI 的复用核心，通过 $ref 引用避免重复定义。组件主要包含以下类别：

引用路径的解析是冒烟检查的常见盲区。例如，$ref: '#/components/schemas/Order' 必须确保 components.schemas 下确实存在 Order 定义。迁移过程中，组件可能被重命名、拆分或合并，导致引用断裂。

3.4 Schema 定义：数据契约的核心

Schema 定义了 API 请求和响应的数据结构，是数据契约最核心的部分。OpenAPI 3.0 使用 Schema Object（基于 JSON Schema Draft-07），而 3.1 直接使用完整的 JSON Schema 2020-12。以下是一个 Schema 定义示例：

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: 用户唯一标识
        email:
          type: string
          format: email
          description: 用户邮箱地址
        displayName:
          type: string
          maxLength: 100
          description: 用户显示名称
        createdAt:
          type: string
          format: date-time
          description: 创建时间
        status:
          type: string
          enum: [active, inactive, suspended]
          description: 用户状态

在冒烟检查中，Schema 定义需要重点验证以下规则：

• 必需字段（required）： 迁移后是否新增或删除了必需字段？这直接影响客户端请求的构造。
• 字段类型与格式： type 和 format 是否匹配？例如 format: email 必须搭配 type: string。
• 枚举值（enum）： 枚举列表是否完整？新增或删除枚举值可能导致业务逻辑异常。
• 嵌套与引用： 嵌套对象和数组的引用是否正确？循环引用是否被正确处理？

3.5 核心结构关系图

下图展示了 OpenAPI 文档中路径、组件和 Schema 之间的引用关系，帮助理解数据契约的依赖链条：

3.6 迁移前后的 Schema 兼容性矩阵

在数据契约冒烟检查中，需要根据 Schema 变更的类型判断是否为破坏性变更。下表总结了常见变更及其影响等级：