3. OpenAPI规范基础：OpenAPI 3.0核心结构、路径与操作定义、请求与响应模型

OpenAPI 规范（原 Swagger 规范）是契约治理中最广泛采用的接口描述语言。它提供了一种与编程语言无关的标准格式，用于定义 RESTful API 的端点、输入输出、认证方式及数据模型。掌握 OpenAPI 3.0 的核心结构，是进行接口演进管理和数据模型优化的前提。

3.1 OpenAPI 3.0 文档核心结构

一个合法的 OpenAPI 3.0 文档是一个 JSON 或 YAML 对象，必须包含以下顶层字段。理解这些字段的层级关系，有助于快速定位契约中的任何定义。

3.2 路径与操作定义

paths 对象是 API 契约的骨架。每个路径是一个相对 URL 模板，其下包含一个或多个 操作对象（Operation Object）。操作对象通过 HTTP 方法（get、post、put、delete、patch 等）作为键名来定义。

3.2.1 路径模板与参数

路径中可以包含花括号包裹的路径参数，例如 /users/{userId}。这些参数必须在路径级别的 parameters 字段中声明，或在操作级别覆盖。

paths:
  /users/{userId}:
    get:
      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'

3.2.2 操作对象的通用字段

每个操作对象可以包含以下关键字段，这些字段直接决定了 API 的可观测性和可测试性。

3.3 请求与响应模型

请求和响应的数据模型是契约治理中最容易产生分歧的部分。OpenAPI 3.0 通过 requestBody 和 responses 字段，结合 components/schemas 中的 Schema 对象，实现了数据模型的声明式管理。

3.3.1 请求体（requestBody）

请求体对象包含 description 和 content 字段。content 是一个映射，键为 MIME 类型（如 application/json），值为媒体类型对象，其中包含 schema 引用。

requestBody:
  description: 创建用户所需的请求体
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateUserRequest'
    application/xml:
      schema:
        $ref: '#/components/schemas/CreateUserRequest'

3.3.2 响应对象（responses）

响应对象以 HTTP 状态码为键。每个响应必须包含 description，并可选地包含 headers 和 content。对于错误响应，建议使用 default 或具体的 4xx/5xx 状态码。

responses:
  '200':
    description: 用户创建成功
    headers:
      X-Request-Id:
        schema:
          type: string
          format: uuid
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  '400':
    description: 请求参数校验失败
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
  '409':
    description: 用户邮箱已存在
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'

3.3.3 Schema 对象与数据模型复用

components/schemas 是数据模型复用的核心仓库。每个 Schema 对象遵循 JSON Schema 规范（OpenAPI 3.0 基于 JSON Schema Draft 7 的子集）。通过 $ref 引用，可以在路径、操作、请求体、响应中反复使用同一个模型。

3.4 契约治理中的 OpenAPI 实践要点

在契约治理流程中，OpenAPI 规范不仅是文档工具，更是自动化校验、代码生成、测试和监控的单一事实来源。以下是三个关键实践方向：

• 版本化契约仓库： 将 OpenAPI 文件纳入 Git 仓库，每次变更通过 Pull Request 触发自动校验（格式校验、破坏性变更检测）。
• 模型复用与收敛： 通过 $ref 引用共享模型，避免不同团队定义语义相同的独立结构。建议建立组织级的 common-schemas.yaml。
• 扩展字段标准化： 使用 x- 前缀扩展字段承载治理元数据，例如 x-owner-team、x-sla-tier、x-deprecated-at，使契约具备可治理性。