2. OpenAPI 规范基础：历史、核心结构与文件组成

OpenAPI 规范（原 Swagger 规范）是 RESTful API 契约的事实标准。理解其演进脉络、3.0 版的核心骨架以及 YAML/JSON 文件的组成要素，是划定 API 契约领域边界的第一步。本章从这三个维度建立基础认知。

2.1 OpenAPI 规范的历史演进

规范经历了从 Swagger 到 OpenAPI 的品牌与治理转变，每一次大版本都显著影响了契约的表达能力。

2.2 OpenAPI 3.0 核心结构

一个 OpenAPI 3.0 文档由四个顶层区域构成，它们共同定义了 API 的契约边界：

1. 元信息层（openapi、info、servers）—— 声明规范版本、API 标题、版本号、基础 URL。
2. 路径层（paths）—— 按资源路径组织所有端点及其操作（GET/POST/PUT/DELETE 等）。
3. 组件层（components）—— 集中定义可复用的 Schema、参数、请求体、响应、安全方案等。
4. 增强层（tags、externalDocs、security）—— 提供分组、外部文档、全局安全声明。

2.3 OpenAPI 文件的基本组成

一个完整的 OpenAPI 3.0 文件（YAML 或 JSON）包含以下必需和可选字段。以下是一个最小可用的契约示例：

openapi: "3.0.3"
info:
  title: 订单服务 API
  version: "1.0.0"
  description: 管理订单的创建、查询与状态变更
servers:
  - url: https://api.example.com/v1
    description: 生产环境
paths:
  /orders:
    get:
      summary: 查询订单列表
      operationId: listOrders
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        "200":
          description: 成功返回订单列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        customerName:
          type: string
        totalAmount:
          type: number
      required:
        - id
        - customerName

2.4 各组成要素详解

2.5 路径与操作的契约结构

每个路径下的操作（Operation）是契约的核心单元，其内部结构决定了 API 的行为边界：

• operationId —— 操作的唯一标识符，在代码生成和领域事件溯源中作为方法签名。
• parameters —— 路径参数、查询参数、请求头参数，定义输入边界。
• requestBody —— 仅适用于 POST/PUT/PATCH，描述请求体的媒体类型与 Schema。
• responses —— 按 HTTP 状态码组织的响应定义，包含媒体类型与 Schema。
• security —— 可覆盖全局安全策略，定义操作级安全边界。

2.6 组件复用与契约边界

components 对象是 OpenAPI 3.0 最重要的架构改进之一。它将类型定义从路径中抽离，形成独立的类型系统：

components:
  schemas:
    Order:
      type: object
      properties:
        id: { type: integer }
        items:
          type: array
          items:
            $ref: "#/components/schemas/OrderItem"
    OrderItem:
      type: object
      properties:
        productId: { type: integer }
        quantity: { type: integer }
        price: { type: number }
  parameters:
    orderId:
      name: orderId
      in: path
      required: true
      schema: { type: integer }
  requestBodies:
    CreateOrder:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Order"

通过 $ref 引用，路径层可以复用组件层的定义。这种机制带来的领域边界优势：

• 单一事实来源 —— Order 类型只定义一次，所有路径引用同一 Schema。
• 类型一致性 —— 避免不同路径对同一资源定义不一致的字段。
• 版本管理 —— 修改组件 Schema 即可全局生效，便于契约版本演进。
• 领域模型映射 —— components/schemas 直接对应领域驱动设计中的聚合根、实体、值对象。