3. OpenAPI 基础结构：五大核心对象

OpenAPI 规范（OAS）定义了一套标准化的元数据格式，用于描述 HTTP API 的契约。一个合法的 OpenAPI 文档由五个顶层字段构成其骨架：openapi、info、servers、paths 和 components。理解这五个字段的职责与边界，是构建可维护、可缓存 API 契约的第一步。

3.1 openapi 字段：版本声明

openapi 字段是文档的版本标识，必须位于文档根节点。它使用 SemVer 格式，声明文档所遵循的 OpenAPI 规范版本。

openapi: "3.0.3"

3.2 info 对象：API 元信息

info 对象提供 API 的元数据，如标题、版本、描述和联系人信息。它是 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.3 servers 对象：连接端点

servers 对象定义 API 的基 URL 和可选的变量替换规则。它告诉客户端“去哪里调用这个 API”。

servers:
  - url: https://api.example.com/v2
    description: 生产环境
  - url: https://staging-api.example.com/v2
    description: 预发布环境

3.4 paths 对象：API 的核心契约

paths 对象是 OpenAPI 文档的核心，它按路径（如 /users）组织所有可用的 API 端点及其操作（GET、POST 等）。每个路径下可以定义多个 HTTP 方法。

paths:
  /users:
    get:
      summary: 获取用户列表
      operationId: listUsers
      responses:
        '200':
          description: 成功返回用户列表
    post:
      summary: 创建新用户
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功

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

components 对象是一个容器，用于存放可复用的 Schema、参数、响应、请求体、头信息等。它通过 $ref 引用机制被 paths 或其他对象调用，避免重复定义。

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name
  parameters:
    userId:
      name: userId
      in: path
      required: true
      schema:
        type: integer

3.6 五大对象的关系与边界

下图展示了 OpenAPI 文档中五个顶层字段的层级关系与数据流向：

3.7 五大字段的缓存影响矩阵

在缓存策略设计中，每个顶层字段的变更都会对缓存产生不同范围的影响。下表总结了各字段变更时的缓存失效范围：

3.8 最佳实践：契约的领域边界

在大型项目中，建议将 OpenAPI 文档按领域边界拆分为多个文件，通过 $ref 进行组合。这有助于隔离缓存影响范围：

1. 按微服务拆分： 每个微服务维护独立的 OpenAPI 文档，只包含自己的 paths 和 components。
2. 按版本拆分： 不同版本的 API 使用独立的文档，避免版本混淆导致缓存污染。
3. 按变更频率拆分： 将稳定的基础 Schema（如 User、Order）与频繁变动的业务端点分离，分别管理缓存生命周期。

# 主文档：api.yaml
openapi: "3.0.3"
info:
  title: 电商平台 API
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    $ref: './paths/users.yaml'
  /orders:
    $ref: './paths/orders.yaml'
components:
  schemas:
    User:
      $ref: './components/user.yaml'
    Order:
      $ref: './components/order.yaml'