📚 课程目录第3章 OpenAPI规范基础

3. OpenAPI 规范基础：OpenAPI 3.0 结构、路径、组件、请求/响应模型

OpenAPI 3.0 是描述 RESTful API 的行业标准规范，在消息契约开发中，它被用来精确描述消息的发布接口（Producer）和消费接口（Consumer）。本章将拆解 OpenAPI 3.0 的核心结构，重点聚焦于路径、组件以及请求/响应模型，为后续将 RabbitMQ 消息映射为 OpenAPI 契约奠定基础。

3.1 OpenAPI 3.0 文档顶层结构

一个标准的 OpenAPI 3.0 文档是一个 JSON 或 YAML 文件，其顶层包含以下关键字段：

字段	必填	说明
`openapi`	是	规范版本号，固定为 `3.0.x`。
`info`	是	API 元信息，包括 title、version、description。
`servers`	否	目标服务器地址列表，用于消息契约时可指定 Broker 连接地址。
`paths`	是	API 路径集合，每个路径对应一个端点（Endpoint）。
`components`	否	可复用的组件仓库，如 schemas、parameters、requestBodies。
`tags`	否	用于分组和分类的标签。

消息契约视角： 在消息中间件场景中，paths 通常映射为 Exchange 名称 + Routing Key，servers 用于声明 RabbitMQ 集群地址，components 则存放消息体的 Schema 定义。

3.2 路径（Paths）与操作（Operations）

paths 是 OpenAPI 文档的核心，它定义了所有可访问的 API 端点。每个路径下可以包含多个 HTTP 方法（如 GET、POST、PUT、DELETE）。在消息契约中，我们通常使用 POST 表示发布消息，GET 表示订阅或拉取消息。

一个典型的路径定义结构如下：

paths:
  /orders/create:
    post:
      operationId: publishOrderCreated
      summary: 发布订单创建消息
      tags:
        - OrderEvents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreated'
      responses:
        '202':
          description: 消息已成功投递到 Exchange

  关键字段说明：
  operationId：唯一标识该操作，用于生成客户端 SDK 方法名。
requestBody：描述消息体的结构和格式。
responses：定义可能的响应状态码和返回结构。
tags：用于逻辑分组，例如按消息类型或业务域划分。

3.3 组件（Components）与可复用模型

components 是 OpenAPI 3.0 引入的重要特性，它允许将 Schema、参数、请求体、响应体等定义为可复用的命名组件，通过 $ref 引用。这极大地减少了文档冗余，并保证了消息体定义的一致性。

组件区域通常包含以下子字段：

schemas：定义数据模型（消息体结构）。
requestBodies：预定义的请求体模板。
responses：预定义的响应模板。
parameters：可复用的路径/查询参数。
headers：可复用的消息头定义。

以下是一个消息体 Schema 的组件定义示例：

components:
  schemas:
    OrderCreated:
      type: object
      required:
        - orderId
        - userId
        - totalAmount
      properties:
        orderId:
          type: string
          format: uuid
          description: 订单唯一标识
        userId:
          type: string
          description: 用户 ID
        totalAmount:
          type: number
          format: float
          description: 订单总金额
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      properties:
        productId:
          type: string
        quantity:
          type: integer
        price:
          type: number

3.4 请求模型（Request Body）与响应模型（Response）

在消息契约中，请求模型描述的是生产者发送的消息体结构，响应模型描述的是 Broker 或消费者返回的确认/状态信息。

模型类型	消息契约中的含义	常见状态码
请求模型（requestBody）	生产者发布到 Exchange 的消息 Payload	202 Accepted（异步投递）
响应模型（responses）	Broker 返回的确认（ACK/NACK）或错误信息	200 OK、202 Accepted、400 Bad Request

响应模型可以定义多个状态码，每个状态码下可以包含详细的 Schema 描述：

responses:
  '202':
    description: 消息已确认接收
    content:
      application/json:
        schema:
          type: object
          properties:
            messageId:
              type: string
              description: RabbitMQ 分配的投递标签
            status:
              type: string
              example: "published"
  '400':
    description: 消息格式错误或路由失败
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'

3.5 OpenAPI 3.0 文档结构总览

下图展示了 OpenAPI 3.0 文档的核心结构及其在消息契约中的映射关系：

3.6 消息契约中的 OpenAPI 最佳实践

常见误区： 直接将 HTTP API 的 OpenAPI 定义照搬到消息契约中，忽略异步消息的语义差异。例如，消息发布通常返回 202 Accepted 而非 200 OK，且不应要求同步响应体。

使用 application/json 作为默认 Content-Type：消息体序列化格式统一，便于跨语言消费。
为每个消息类型定义独立的 Schema：避免使用泛型 object，保证契约的强类型约束。
在 operationId 中体现消息方向：例如 publishOrderCreated、consumePaymentProcessed。
利用 tags 进行消息域分组：如 OrderEvents、PaymentEvents，便于在工具中筛选。
在 description 中注明 Exchange 类型和 Routing Key 规则：为消费者提供完整的路由上下文。