3. OpenAPI 文档核心组件

一份完整的 OpenAPI 文档由多个顶层对象组成，它们共同定义了 API 的元信息、网络地址、端点路由、可复用组件以及标签分类。理解这五个核心组件是进行契约校验的前提。

3.1 核心组件总览

下表列出了 OpenAPI 文档中五个必选或常用的顶层字段及其职责：

3.2 info 对象：API 的身份证

info 对象提供 API 的元数据，是消费者识别 API 身份的第一入口。其核心字段包括：

• title（必填）：API 的名称，如“用户管理服务”。
• version（必填）：文档版本号，建议遵循语义化版本（SemVer），如 1.0.0。
• description：对 API 功能的详细说明，支持 CommonMark 语法。
• contact：维护团队的联系方式（name、url、email）。
• license：API 使用的许可协议（name、url）。

info:
  title: 电商订单服务
  version: "2.1.0"
  description: 提供订单创建、查询、退款等核心能力
  contact:
    name: API 团队
    email: api@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

3.3 servers 对象：API 的网络地址

servers 是一个数组，每个元素定义一个服务器。它替代了 Swagger 2.0 中的 host、basePath 和 schemes，提供了更灵活的多环境支持。

servers:
  - url: https://{env}.api.example.com/v2
    description: 动态环境
    variables:
      env:
        default: prod
        enum:
          - prod
          - staging
          - dev
  - url: http://localhost:8080
    description: 本地开发

3.4 paths 对象：API 的路由地图

paths 是 OpenAPI 文档的核心，它定义了所有可访问的端点及其操作。每个路径下可以包含一个或多个 HTTP 方法（get、post、put、delete 等）。

• 路径模板：支持路径参数，如 /users/{userId}。
• 操作对象：每个方法下可定义 parameters、requestBody、responses、tags 等。
• summary / description：对端点的简短说明和详细描述。

paths:
  /orders:
    get:
      tags: [订单]
      summary: 获取订单列表
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功返回订单列表
    post:
      tags: [订单]
      summary: 创建新订单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrder'
      responses:
        '201':
          description: 订单创建成功

3.5 components 对象：可复用组件仓库

components 是一个容器，用于集中定义可被 $ref 引用的对象。它避免了在多个端点中重复定义相同的 schema、参数或响应。

components 内部包含以下常用分类：

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
  parameters:
    pageSize:
      name: page_size
      in: query
      schema:
        type: integer
        default: 20
  responses:
    NotFound:
      description: 资源未找到
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string

3.6 tags 对象：端点的分类标签

tags 是一个顶层数组，用于对 paths 中的端点进行逻辑分组。每个标签可以包含名称和描述，工具链（如 Swagger UI）会根据标签对端点进行分组展示。

tags:
  - name: 订单
    description: 订单创建、查询、退款相关接口
  - name: 用户
    description: 用户注册、登录、信息管理
  - name: 商品
    description: 商品浏览、搜索、详情

在 paths 中引用标签：

paths:
  /products:
    get:
      tags: [商品]
      summary: 获取商品列表

3.7 核心组件关系图

下图展示了五个核心组件在 OpenAPI 文档中的层级关系与数据流向：

3.8 组件间的引用关系

下图展示了 paths 与 components 之间通过 $ref 建立的引用链路，这是契约校验中解析依赖的关键路径：

3.9 契约校验视角下的核心组件

从契约测试的角度，五个核心组件各自承担不同的校验职责：