3. OpenAPI 文档结构：五大核心对象

一份标准的 OpenAPI 文档（通常为 JSON 或 YAML 格式）由五个顶层对象构成其骨架。理解这五个对象的职责与层级关系，是编写高质量接口契约的基础。本章将逐一拆解 info、servers、paths、components 和 tags 对象的结构与使用规范。

3.1 info 对象：API 元数据

info 对象是文档的“身份证”，提供 API 的基本描述信息。它是唯一一个必须存在的顶层对象。

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

3.2 servers 对象：连接端点

servers 对象定义 API 的基础 URL 列表。每个 server 包含 url（必需）和 description（可选），支持变量模板。

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

当使用变量模板时，可在 variables 中声明默认值：

servers:
  - url: https://{environment}.example.com/{version}
    variables:
      environment:
        default: api
        enum: [api, staging, dev]
      version:
        default: v2

3.3 paths 对象：API 端点与操作

paths 是文档的核心，以相对路径为键，映射到该路径支持的 HTTP 方法（get、post、put、delete、patch 等）。每个操作可定义 parameters、requestBody、responses 等。

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

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

components 是文档的“工具箱”，集中管理可复用的 Schema、参数、响应、请求体、安全方案等。通过 $ref 引用，避免重复定义。

components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        total:
          type: number
        status:
          type: string
          enum: [pending, paid, shipped]
    CreateOrderRequest:
      type: object
      required: [productId, quantity]
      properties:
        productId:
          type: integer
        quantity:
          type: integer
          minimum: 1
  parameters:
    orderIdParam:
      name: orderId
      in: path
      required: true
      schema:
        type: integer
  responses:
    NotFound:
      description: 资源未找到
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string

3.5 tags 对象：文档分组与导航

tags 对象为路径操作提供逻辑分组。每个 tag 包含 name（必需）和可选的 description。在 paths 中通过 tags 字段关联。

tags:
  - name: 订单
    description: 订单创建、查询、退款操作
  - name: 商品
    description: 商品信息与库存管理
  - name: 用户
    description: 用户认证与资料管理

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

tags 在文档工具（如 Swagger UI）中会生成分组标题，提升可读性。一个操作可以关联多个 tag。

3.6 对象层级速查表