3. OpenAPI 规范入门：OpenAPI 3.0 核心结构与 YAML/JSON 语法基础

在消息队列开发中采用“契约先行”模式，第一步就是掌握契约的书写语言——OpenAPI 3.0 规范。本章将拆解 OpenAPI 3.0 的四大核心顶层结构（info、paths、components、schemas），并同步讲解 YAML 与 JSON 两种序列化格式的基础语法，为后续编写消息队列 API 契约打下坚实基础。

3.1 OpenAPI 3.0 顶层结构总览

一份合法的 OpenAPI 3.0 文档，本质上是一个描述 API 的元数据文件。其顶层结构由以下几个关键对象组成：

顶层字段 必填 作用描述
openapi 是 声明使用的 OpenAPI 规范版本号，例如 "3.0.3"
info 是 提供 API 的元数据：标题、版本、描述、联系人等
paths 是 定义所有可用的 API 端点（路径）及其支持的 HTTP 方法
components 否 存放可复用的对象，如 schemas、parameters、responses 等
servers 否 指定 API 的基础 URL 列表，用于运行时连接
tags 否 对 API 端点进行逻辑分组，常用于文档生成
实践要点：在消息队列场景中，servers 字段通常指向消息代理的网关地址；tags 可用于区分“生产端”与“消费端”接口。

3.2 核心结构详解

3.2.1 info：API 的身份铭牌

info 对象是 API 文档的“身份证”，必须包含 title 和 version。推荐同时提供 description 字段，用简明语言说明该 API 在消息队列中的职责。

info:
  title: 消息队列生产端 API
  version: "1.0.0"
  description: 提供消息发布、批量发送及事务消息支持
  contact:
    name: 消息中间件团队
    email: mq-team@example.com

3.2.2 paths：API 的端点地图

paths 是 OpenAPI 文档的核心，它按 URL 路径组织所有可用的操作。每个路径下可定义多个 HTTP 方法（get、post、put、delete 等）。在消息队列场景中，post 方法常用于发送消息，get 方法常用于拉取消息或查询队列状态。

paths:
  /queues/{queueName}/messages:
    post:
      summary: 发送单条消息到指定队列
      parameters:
        - name: queueName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '201':
          description: 消息发送成功
        '400':
          description: 请求参数错误

3.2.3 components/schemas：数据模型的复用仓库

components/schemas 是定义数据结构的核心区域。通过 $ref 引用机制，可以在 paths 中反复使用这些模型，避免重复定义。对于消息队列，这里通常定义 Message、QueueInfo、ConsumerGroup 等核心模型。

components:
  schemas:
    Message:
      type: object
      required:
        - messageId
        - payload
      properties:
        messageId:
          type: string
          description: 全局唯一消息 ID
        payload:
          type: string
          description: 消息体内容（JSON 字符串）
        priority:
          type: integer
          description: 消息优先级，1-10
          default: 5
        timestamp:
          type: string
          format: date-time
          description: 消息产生时间
契约先行关键：在编写 schemas 时，消息队列开发者应优先定义 Message 结构。一旦 Message 模型确定，生产端和消费端的代码生成、数据校验、文档同步都将以此为准。

3.3 YAML 与 JSON 语法基础

OpenAPI 3.0 支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释友好，成为社区首选；JSON 则在系统间交换时更通用。以下对比两者的核心语法差异：

语法特性 YAML JSON
缩进 使用空格缩进表示层级（推荐 2 空格） 使用花括号 {} 嵌套
字符串 通常不加引号；特殊字符时可加双引号 必须使用双引号
注释 支持 # 行注释 不支持注释
数组 使用 - 列表项 使用方括号 []
引用 支持锚点 & 和别名 * 不支持

以下展示同一段 OpenAPI 定义在 YAML 和 JSON 中的写法对比：

# YAML 版本
openapi: "3.0.3"
info:
  title: 队列管理 API
  version: "2.1.0"
paths:
  /health:
    get:
      summary: 健康检查
      responses:
        '200':
          description: 服务正常
// JSON 版本
{
  "openapi": "3.0.3",
  "info": {
    "title": "队列管理 API",
    "version": "2.1.0"
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "健康检查",
        "responses": {
          "200": {
            "description": "服务正常"
          }
        }
      }
    }
  }
}
常见陷阱：YAML 对缩进极其敏感，禁止使用 Tab 键，必须使用空格。一个常见的错误是 paths 下的路径键（如 /queues/{queueName}）忘记缩进，导致整个文档解析失败。建议在编辑器中开启“显示空格”功能。

3.4 核心结构关系图

下图展示了 OpenAPI 3.0 文档中 info、paths、components/schemas 之间的引用与依赖关系：

OpenAPI 3.0 核心结构关系图 OpenAPI 文档根 info (元数据) paths (端点定义) components/schemas title: 消息队列 API version: 1.0.0 /queues/{name}/messages post / get / delete Message QueueInfo $ref 契约先行核心流程 先定义 schemas → 再在 paths 中引用 → 最后生成代码与文档

3.5 消息队列场景中的典型结构示例

以下是一个完整的 OpenAPI 3.0 文档片段，展示如何为消息队列的“发送消息”和“消费消息”两个核心操作定义契约：

openapi: "3.0.3"
info:
  title: 消息队列核心 API
  version: "1.0.0"
  description: 支持生产端发送与消费端拉取消息

paths:
  /produce/{topic}:
    post:
      summary: 向指定主题发送消息
      parameters:
        - name: topic
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProduceRequest'
      responses:
        '200':
          description: 消息发送成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProduceResponse'

  /consume/{topic}/poll:
    get:
      summary: 从指定主题拉取消息
      parameters:
        - name: topic
          in: path
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          schema:
            type: integer
            default: 5000
      responses:
        '200':
          description: 返回消息列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'

components:
  schemas:
    ProduceRequest:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: 消息键，用于分区路由
        value:
          type: string
          description: 消息体
        headers:
          type: object
          description: 自定义消息头

    ProduceResponse:
      type: object
      properties:
        offset:
          type: integer
          description: 消息在分区中的偏移量
        partition:
          type: integer
          description: 目标分区编号

    Message:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
        offset:
          type: integer
        partition:
          type: integer
        timestamp:
          type: string
          format: date-time
学习建议：初学者可以先从 YAML 格式入手，使用 Swagger Editor 或 Stoplight Studio 等工具进行可视化编辑。这些工具能实时校验语法错误，并自动生成对应的 JSON 版本和 API 文档预览。

3.6 本章小结

← 上一章 📖 返回目录 下一章 →