4. OpenAPI 文档结构详解：核心对象与契约骨架

一份符合 OpenAPI 3.0 规范的 API 文档，本质上是一个结构化的 JSON 或 YAML 文件。理解其顶层对象的职责与关系，是进行企业级 API 契约治理的第一步。本章将深入剖析五个核心顶层对象：info、servers、paths、components 和 tags，它们共同构成了 API 契约的完整骨架。

4.1 文档顶层结构总览

一个标准的 OpenAPI 文档，其顶层包含以下关键字段。下面的 SVG 图展示了这些核心对象之间的逻辑关系与数据流向。

4.2 info 对象：API 的身份铭牌

info 对象是 API 文档的元数据声明，它定义了 API 的名称、版本、描述以及联系信息。这是消费者了解 API 的第一入口，也是企业 API 目录治理的基础字段。

4.3 servers 对象：API 的网络地址簿

servers 对象是一个数组，用于指定 API 服务的一个或多个基础 URL（Base URL）。每个 server 对象包含 url 和 description 字段，并可选的 variables 字段用于实现 URL 模板化。

servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://staging-api.example.com/v1
    description: 预发布环境
  - url: http://localhost:8080/api/v1
    description: 本地开发环境

在企业级治理中，servers 对象通常由 CI/CD 流水线在构建阶段动态注入，而非由开发人员在代码中硬编码。这确保了不同环境（开发、测试、预发布、生产）使用正确的端点配置。

4.4 paths 对象：API 的核心路由表

paths 对象是 OpenAPI 文档中体量最大、最核心的部分。它是一个映射（Map），键是 API 的相对路径（如 /users/{userId}），值是一个 Path Item 对象，该对象定义了针对此路径的所有 HTTP 方法（GET、POST、PUT、DELETE 等）。

每个操作（Operation）内部包含以下关键子字段：

• parameters：路径参数、查询参数、请求头参数的定义。
• requestBody：请求体的描述，仅在 POST、PUT、PATCH 等方法中使用。
• responses：所有可能的 HTTP 状态码响应定义，是契约的核心。
• security：该操作的安全认证要求，可覆盖全局安全定义。
• tags：引用 tags 对象中定义的标签，用于逻辑分组。

4.5 components 对象：可复用组件的仓库

components 对象是 OpenAPI 的“复用工厂”，它允许你定义一次 Schema、参数、响应、请求体、安全方案等，然后在 paths 或其他地方通过 $ref 引用。这极大地减少了文档冗余，提升了维护性。

components 内部包含以下常用子对象：

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
  parameters:
    pageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        default: 20

4.6 tags 对象：API 操作的逻辑分组器

tags 对象是一个数组，用于声明 API 文档中使用的所有标签。每个标签包含 name 和可选的 description 字段。在 paths 对象的每个操作中，可以通过 tags 字段引用这些标签，从而将不同的端点归类到同一逻辑分组下。

tags:
  - name: 用户管理
    description: 用户注册、登录、信息查询与更新
  - name: 订单管理
    description: 订单创建、支付、查询与取消
  - name: 商品目录
    description: 商品浏览、搜索与详情

在企业级 API 治理中，tags 的命名规范至关重要。建议采用 “领域.子域” 的命名模式，例如 用户.认证、订单.生命周期，这有助于在 API 治理平台中自动生成多级目录。

4.7 核心对象对比总结

下表从职责、治理关注点和常见误区的角度，对五个核心对象进行横向对比：