2. OpenAPI 文档结构：文档顶层结构解析

OpenAPI 3.x 规范定义了一套标准化的顶层结构，用于描述整个 API 的元数据、连接信息、路径、组件复用以及文档扩展。理解这 7 个顶层字段是编写、解析和维护 OpenAPI 文档的基础。

2.1 顶层字段总览

一个合法的 OpenAPI 文档必须包含 openapi 和 info 字段，其余字段按需声明。下表列出了所有顶层字段及其用途：

字段名	必需	类型	核心用途
openapi	是	string	声明规范版本号，如 3.0.3 或 3.1.0
info	是	Info Object	API 标题、版本、描述、联系人、许可信息
servers	否	[Server Object]	API 的基础 URL 列表，支持变量模板
paths	否	Paths Object	所有 API 端点及其操作（GET/POST 等）
components	否	Components Object	可复用的 schema、参数、响应、安全方案等
tags	否	[Tag Object]	对路径进行逻辑分组，用于文档导航
externalDocs	否	External Documentation Object	指向外部文档的链接，如业务说明或 SDK 指南

2.2 顶层结构关系图

下图展示了 OpenAPI 文档的顶层字段及其逻辑分组关系：

2.3 各字段详解

2.3.1 openapi — 规范版本声明

该字段的值必须是语义化版本号，目前主流版本为 3.0.3 和 3.1.0。版本决定了文档解析器的行为。

openapi: "3.0.3"

2.3.2 info — API 元信息

包含标题、描述、版本号、联系人及许可信息。在合规审计中，contact 字段必须填写真实团队邮箱。

info:
  title: 支付网关 API
  description: 提供订单创建、退款、对账等核心支付能力
  version: "2.1.0"
  contact:
    name: API 支持团队
    email: api-support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

2.3.3 servers — 服务器连接信息

支持多环境配置与变量模板。生产环境与沙箱环境必须分开声明。

servers:
  - url: https://api.example.com/v2
    description: 生产环境
  - url: https://sandbox-api.example.com/v2
    description: 沙箱测试环境
  - url: https://{env}-api.example.com/{version}
    description: 模板化环境
    variables:
      env:
        default: prod
        enum: [prod, sandbox, staging]
      version:
        default: v2

2.3.4 paths — 路径与操作

文档的核心部分，定义每个端点的请求方法、参数、请求体、响应及安全要求。路径支持参数化模板。

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

2.3.5 components — 可复用组件

集中管理 schemas、parameters、responses、securitySchemes 等，通过 $ref 引用。减少重复，提升文档一致性。

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        amount:
          type: number
          format: float
        status:
          type: string
          enum: [pending, paid, cancelled]
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

2.3.6 tags — 逻辑分组标签

用于对 paths 中的操作进行分组，在生成的文档中形成目录结构。每个标签可以附带描述。

tags:
  - name: 订单
    description: 订单创建、查询、退款相关接口
  - name: 支付
    description: 支付渠道、回调、对账相关接口

2.3.7 externalDocs — 外部文档链接

指向业务需求文档、SDK 使用指南或合规政策文件。

externalDocs:
  description: 支付业务需求文档 v3.2
  url: https://wiki.example.com/payment/requirements

2.4 完整最小示例

以下是一个符合 OpenAPI 3.0.3 规范的最小文档骨架：

openapi: "3.0.3"
info:
  title: 最小示例 API
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
paths:
  /health:
    get:
      responses:
        '200':
          description: 服务正常
components: {}
tags:
  - name: 系统
externalDocs:
  description: 运维手册
  url: https://ops.example.com

2.5 字段依赖与常见错误

错误场景	原因	合规影响
缺少 openapi 字段	解析器无法确定规范版本	文档不可用，工具链报错
info.version 与 API 实际版本不一致	版本管理混乱	审计追溯失败
servers 未声明沙箱环境	测试与生产混用	安全合规不通过
paths 中直接内嵌复杂 schema 而不使用 $ref	组件未复用	文档膨胀，维护成本高
tags 未定义但路径中使用了 tags 引用	标签引用断裂	文档生成工具可能忽略分组