2. OpenAPI 基础：规范起源、YAML/JSON 语法与核心结构

在消息队列开发中，API 契约是服务间通信的“法律文件”。OpenAPI 规范（原 Swagger）已成为描述 RESTful API 的事实标准。本章从规范起源讲起，快速掌握 YAML/JSON 语法，并深入 OpenAPI 3.0 的三大核心结构：info、paths、components。

2.1 OpenAPI 规范起源与演进

OpenAPI 规范最初由 Swagger 项目于 2011 年提出，2015 年捐赠给 Linux 基金会并更名为 OpenAPI Initiative。目前主流版本为 OpenAPI 3.0.x（2017 年发布），相比 2.0 版本在可重用性、安全性描述和链接支持上大幅增强。

2.2 YAML / JSON 语法基础

OpenAPI 规范支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释支持好，成为首选编写格式；JSON 常用于程序解析和传输。

2.2.1 核心语法对比

2.2.2 常见陷阱与避坑

• Tab 与空格混用：YAML 禁止 Tab 缩进，必须使用空格。
• 字符串未加引号导致类型推断错误：例如 version: 3.0 会被解析为浮点数，应写为 version: "3.0"。
• JSON 中尾随逗号：JSON 不允许最后一个元素后加逗号，YAML 无此限制。

# YAML 示例：OpenAPI 3.0 文档头部
openapi: "3.0.3"
info:
  title: 消息队列管理 API
  version: "1.0.0"
  description: 用于管理 Kafka 主题和消费者的 RESTful 接口
servers:
  - url: https://api.example.com/v1

2.3 OpenAPI 3.0 核心结构

一个标准的 OpenAPI 3.0 文档由三个顶层字段构成核心骨架：info（元信息）、paths（路径与操作）、components（可复用组件）。

2.4 info：API 元信息

info 对象提供 API 的标题、版本、描述等元数据，是每个 OpenAPI 文档的必填字段。

info:
  title: 消息队列管理 API
  description: |
    提供 Kafka 主题创建、消费者组查询、消息发送等操作。
    详细文档请参考内部 Wiki。
  version: "2.1.0"
  contact:
    name: 消息中间件团队
    email: mq-team@company.com
    url: https://wiki.company.com/mq
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

2.5 paths：API 路径与操作

paths 是 OpenAPI 文档的核心，定义所有可访问的端点及其 HTTP 方法、参数、请求体和响应。

2.5.1 路径定义结构

paths:
  /topics:
    get:
      summary: 获取所有主题列表
      operationId: listTopics
      parameters:
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 主题列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicList'
    post:
      summary: 创建新主题
      operationId: createTopic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTopicRequest'
      responses:
        '201':
          description: 创建成功
        '409':
          description: 主题已存在

2.5.2 路径设计最佳实践

2.6 components：可复用组件

components 是 OpenAPI 3.0 最重要的增强之一，它将可复用的数据结构、参数、响应、请求体等集中定义，通过 $ref 引用，避免重复编写。

2.6.1 常用组件类型

2.6.2 消息队列场景的 Schema 示例

components:
  schemas:
    Topic:
      type: object
      required:
        - name
        - partitions
        - replicationFactor
      properties:
        name:
          type: string
          description: 主题名称
          example: "order-events"
        partitions:
          type: integer
          minimum: 1
          default: 3
        replicationFactor:
          type: integer
          minimum: 1
          maximum: 5
          default: 2
        configs:
          type: object
          description: 主题级别配置（如 retention.ms）
          additionalProperties:
            type: string
    TopicList:
      type: object
      properties:
        topics:
          type: array
          items:
            $ref: '#/components/schemas/Topic'
        totalCount:
          type: integer

2.7 本章小结

• OpenAPI 规范从 Swagger 演进而来，3.0 版本引入 components 大幅提升可维护性。
• YAML 是编写 OpenAPI 的首选格式，注意缩进和类型推断陷阱。
• 核心结构 info 描述 API 元信息，paths 定义端点与操作，components 集中管理可复用组件。
• 消息队列场景中，善用 $ref 引用和 operationId 命名规范，可显著提升 API 文档的可读性和维护效率。