📚 课程目录第4章 OpenAPI规范入门

4. OpenAPI规范入门：OpenAPI 3.0核心结构（info、paths、components）、YAML/JSON语法基础

在消息队列任务接口的契约化设计中，OpenAPI 3.0 是描述 RESTful API 的事实标准。本章将拆解其核心结构，并掌握 YAML/JSON 两种描述语言的书写规范，为后续编写消息队列接口文档打下坚实基础。

4.1 OpenAPI 3.0 文档的顶层骨架

一份合法的 OpenAPI 3.0 文档，必须包含以下三个顶层字段：openapi、info、paths。此外，components 是复用定义的核心区域，虽非强制，但在实际项目中几乎必用。

字段	必填	说明
`openapi`	是	声明遵循的 OpenAPI 版本号，例如 `"3.0.3"`
`info`	是	描述 API 的元信息：标题、版本、描述、联系人等
`paths`	是	定义所有可访问的端点路径及其 HTTP 方法、请求/响应结构
`components`	否	集中存放可复用的 schema、参数、响应、请求体等定义

  关键认知： OpenAPI 文档本质上是一个自描述的 API 契约。只要提供 openapi + info + paths，工具链就能生成文档、Mock 服务、客户端 SDK。

4.2 info 对象：API 的身份铭牌

info 对象为 API 提供标题、版本号、描述等元数据。在消息队列场景中，建议在 description 中注明队列类型、消息格式、可靠性等级。

info:
  title: 消息队列任务管理 API
  description: |
    提供消息的发布、消费、确认、重试及死信管理。
    底层使用 RabbitMQ 作为消息代理，消息体采用 JSON 格式。
  version: "1.0.0"
  contact:
    name: 消息中间件团队
    email: mq-team@example.com

实践建议： version 字段建议使用语义化版本号（SemVer），如 "1.2.3"。每次接口变更时同步更新，便于消费者感知兼容性变化。

4.3 paths 对象：API 的路径地图

paths 是文档的核心，它按 URL 路径组织，每个路径下可定义多个 HTTP 方法（GET、POST、PUT、DELETE 等）。每个方法内部包含 parameters、requestBody、responses 等子字段。

paths:
  /tasks:
    get:
      summary: 获取待消费消息列表
      parameters:
        - name: queueName
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回消息列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'
    post:
      summary: 发布一条新消息
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '201':
          description: 消息发布成功

避坑提醒： 路径参数（如 /tasks/{taskId}）必须在 parameters 中声明 in: path，且 required: true。漏掉 required 会导致生成的 Mock 服务无法正确解析路径。

4.4 components 对象：复用定义的仓库

components 下最常用的是 schemas（数据模型）、parameters（公共参数）、responses（公共响应）。通过 $ref 引用，避免在多个路径中重复定义相同结构。

components:
  schemas:
    Message:
      type: object
      properties:
        id:
          type: string
          format: uuid
        body:
          type: string
          description: 消息体内容
        timestamp:
          type: string
          format: date-time
        retryCount:
          type: integer
          minimum: 0
      required:
        - id
        - body
    PublishRequest:
      type: object
      properties:
        queueName:
          type: string
        payload:
          type: object
      required:
        - queueName
        - payload

  复用优势： 当消息模型变更时，只需修改 components.schemas.Message 一处，所有引用该 schema 的路径自动同步更新，极大降低维护成本。

4.5 YAML 与 JSON 语法基础对比

OpenAPI 文档支持 YAML 和 JSON 两种格式。YAML 因其可读性高、注释友好，成为社区首选；JSON 则在程序生成和传输场景中更常见。

特性	YAML	JSON
缩进	使用空格缩进（通常 2 空格），禁止 Tab	使用花括号 `{}` 和方括号 `[]` 嵌套
注释	支持 `#` 行注释	不支持注释
字符串	可省略引号，特殊字符需加引号	必须使用双引号 `"`
多行文本	使用 `\|` 保留换行，`>` 折叠换行	使用 `\n` 转义
引用	支持锚点 `&` 和别名 `*`	不支持

# YAML 示例（推荐用于手写文档）
openapi: "3.0.3"
info:
  title: 消息队列 API
  version: "1.0.0"
paths:
  /health:
    get:
      summary: 健康检查
      responses:
        '200':
          description: 服务正常

// JSON 示例（适合程序生成）
{
  "openapi": "3.0.3",
  "info": {
    "title": "消息队列 API",
    "version": "1.0.0"
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "健康检查",
        "responses": {
          "200": {
            "description": "服务正常"
          }
        }
      }
    }
  }
}

选型建议： 在课程项目中，我们统一使用 YAML 编写 OpenAPI 文档。YAML 的注释能力对教学和团队协作非常友好，且与 Swagger Editor、Stoplight 等工具配合最佳。

4.6 OpenAPI 3.0 核心结构总览

下图展示了 OpenAPI 3.0 文档的顶层结构及各部分之间的引用关系，帮助建立全局视角。

4.7 从 YAML 到 Mock 服务的快速验证

编写完 OpenAPI 文档后，可使用 prism 或 swagger-cli 快速启动 Mock 服务，验证接口定义的正确性。

# 使用 Prism 启动 Mock 服务（基于 OpenAPI 文档）
npx @stoplight/prism-cli mock ./message-queue-api.yaml

# 测试 Mock 端点
curl http://localhost:4010/tasks?queueName=order.queue

快速反馈： Mock 服务会依据 paths 中的 responses 定义返回示例数据。如果返回 500 或结构异常，说明文档中存在语法错误或引用断裂，需立即修正。

4.8 本章小结

OpenAPI 3.0 文档 由 openapi、info、paths 三个必填字段构成，components 提供复用能力。
info 对象 承载 API 的标题、版本、描述等元信息，是文档的“身份证”。
paths 对象 定义所有端点及其操作，是文档的核心业务逻辑区。
components 对象 通过 $ref 引用机制，避免重复定义，提升维护效率。
YAML 因可读性和注释支持，是手写 OpenAPI 文档的首选格式；JSON 更适合程序生成和传输。
编写完成后，立即启动 Mock 服务验证文档的正确性，形成“编写-验证”的快速闭环。