3. OpenAPI 文档结构详解

OpenAPI 3.x 规范文档是一个自描述的 JSON 或 YAML 文件，其顶层结构由六个核心对象构成。理解这些对象的职责、层级关系以及约束规则，是进行契约驱动 API 设计治理的基础。本章将逐一剖析 info、servers、paths、components、tags 和 externalDocs 六个顶层对象。

3.1 info 对象：API 元数据声明

info 对象提供 API 的标题、版本、描述、联系方式等元数据。它是 API 消费者和治理工具识别 API 身份的第一入口。

info:
  title: 订单服务 API
  version: 2.1.0
  description: 提供订单创建、查询、状态变更等核心能力。
  contact:
    name: 订单团队
    email: order-team@company.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

3.2 servers 对象：运行时环境定义

servers 对象是一个数组，用于指定 API 服务的一个或多个运行时 URL 及对应的描述信息。它替代了 OpenAPI 2.0 中的 host、basePath 和 schemes 字段，提供了更灵活的环境管理能力。

• 多环境支持： 可同时定义生产、预发布、测试等多个环境的服务器地址。
• 变量模板： 支持 {variable} 语法，实现动态 URL 构建。
• 描述信息： 每个服务器对象可附带 description，说明环境用途。

servers:
  - url: https://api.example.com/v2
    description: 生产环境
  - url: https://staging-api.example.com/v2
    description: 预发布环境
  - url: https://{tenant}.api.example.com/v2
    description: 多租户环境
    variables:
      tenant:
        default: demo
        enum:
          - demo
          - customer-a
          - customer-b

3.3 paths 对象：API 端点与操作

paths 对象是 OpenAPI 文档的核心，它定义了所有可用的 API 端点（Endpoint）及其支持的 HTTP 方法（GET、POST、PUT、DELETE 等）。每个路径下可包含多个操作对象（Operation Object）。

paths:
  /orders/{orderId}:
    get:
      operationId: getOrderById
      tags:
        - 订单查询
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功返回订单详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: 订单不存在

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

components 对象是 OpenAPI 的复用机制核心，它定义了可在文档中多处引用的 Schema、参数、响应、请求体、头信息等。通过 $ref 引用机制，避免重复定义，降低维护成本。

components 包含以下子对象：

• schemas：数据模型定义，最常用的组件类型。
• parameters：可复用的参数定义。
• responses：可复用的响应定义。
• requestBodies：可复用的请求体定义。
• headers：可复用的头信息定义。
• securitySchemes：安全认证方案定义。
• links：操作间的链接关系定义。
• callbacks：回调操作定义。

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - confirmed
            - shipped
            - delivered
        totalAmount:
          type: number
          format: float
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  parameters:
    pageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
    limitParam:
      name: limit
      in: query
      schema:
        type: integer
        default: 20

3.5 tags 对象：操作分组与分类

tags 对象是一个数组，用于对 API 操作进行逻辑分组。每个 Tag 包含 name 和可选的 description 字段。在 API 文档展示工具（如 Swagger UI）中，Tag 通常作为目录分组标题。

tags:
  - name: 订单管理
    description: 订单的创建、查询、修改和删除操作
  - name: 支付处理
    description: 支付相关的接口，包括发起支付、查询支付状态
  - name: 物流追踪
    description: 物流信息查询与更新

在 paths 的操作对象中，通过 tags 字段引用：

paths:
  /orders:
    post:
      tags:
        - 订单管理
      operationId: createOrder
      # ...

3.6 externalDocs 对象：外部文档链接

externalDocs 对象用于指向 API 相关的外部文档资源，如用户手册、架构设计文档、变更日志等。它包含两个字段：description（可选）和 url（必需）。

externalDocs:
  description: 订单服务架构设计文档
  url: https://wiki.company.com/order-service-architecture

externalDocs 也可在 Tag 级别使用，为特定分组提供更详细的外部参考：

tags:
  - name: 支付处理
    description: 支付相关接口
    externalDocs:
      description: 支付系统集成指南
      url: https://wiki.company.com/payment-integration

3.7 六个对象的治理优先级与常见错误

在契约驱动 API 设计治理中，六个顶层对象的治理优先级不同。下表总结了各对象的治理关注点及常见错误：