2. OpenAPI 规范基础：OAS 版本演进、核心结构与 YAML/JSON 语法

2.1 OpenAPI Specification (OAS) 版本演进

OpenAPI 规范（OAS）起源于 Swagger 规范，自 2015 年捐赠给 Linux 基金会下的 OpenAPI Initiative 后，已成为描述 RESTful API 的行业标准。理解版本演进有助于在中间件消息契约中选择正确的规范版本。

版本 发布时间 核心变化 中间件适配建议
Swagger 2.0 2014 首次广泛采用，支持基本 REST 描述 部分老旧消息网关仍在使用，建议迁移
OpenAPI 3.0.x 2017-2020 引入 components、oneOf/anyOf、server 对象、增强 callback 当前主流版本，消息契约推荐使用 3.0.3
OpenAPI 3.1.0 2021 与 JSON Schema 2020-12 对齐，支持 webhook、examples 增强 适合新项目，但工具链兼容性需验证
版本选择建议： 对于中间件消息契约环境，推荐使用 OpenAPI 3.0.3。该版本在工具链支持、消息代理适配（如 Kafka、RabbitMQ 的异步 API 扩展）方面最为成熟。若项目需要与 JSON Schema 深度集成，可选用 3.1.0。

2.2 核心结构全景

一个标准的 OpenAPI 文档由四个顶层对象构成。下面的 SVG 展示了它们之间的层级关系与数据流向。

OpenAPI 文档核心结构 OpenAPI 文档根 openapi 版本声明 info 元数据 paths 端点与操作 components 可复用组件 /orders /users schemas parameters 关键说明 • openapi：必须位于文档顶部，声明使用的 OAS 版本号，如 "3.0.3"。 • info：包含标题、描述、版本号、联系信息等元数据。 • paths：定义所有 API 端点及其支持的 HTTP 方法（GET、POST 等）。 • components：集中管理可复用的 schema、参数、响应、请求体等，通过 $ref 引用。

2.3 核心对象详解

2.3.1 openapi 与 info

openapi 字段声明规范版本，info 提供 API 的元数据。这是文档的“身份证”。

openapi: "3.0.3"
info:
  title: "中间件消息契约 - 订单服务"
  description: "用于订单创建、查询、状态变更的消息契约定义"
  version: "1.0.0"
  contact:
    name: "中间件架构组"
    email: "middleware@example.com"

2.3.2 paths：端点与操作

paths 是 API 的核心，定义每个端点支持的 HTTP 方法及其请求/响应结构。在中间件消息契约中，paths 通常映射到消息主题（Topic）或队列（Queue）的操作。

paths:
  /orders:
    post:
      summary: "创建订单消息"
      operationId: "createOrder"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: "订单创建成功"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'

2.3.3 components：可复用组件

components 是 OAS 3.0 引入的关键改进，通过 $ref 引用避免重复定义。在消息契约中，schemas 是最常用的子对象。

components:
  schemas:
    OrderCreate:
      type: object
      required:
        - orderId
        - productCode
        - quantity
      properties:
        orderId:
          type: string
          description: "订单唯一标识"
        productCode:
          type: string
          description: "产品编码"
        quantity:
          type: integer
          minimum: 1
          description: "数量"
    OrderResponse:
      type: object
      properties:
        status:
          type: string
          enum: [SUCCESS, FAILED]
        message:
          type: string

2.4 YAML / JSON 语法基础

OpenAPI 文档支持 YAML 和 JSON 两种格式。YAML 因其可读性高、注释支持好，是编写消息契约的首选。JSON 常用于程序化生成或工具链交换。

特性 YAML JSON
可读性 高，缩进表示层级 中等，大量花括号与引号
注释 支持 # 注释 不支持原生注释
数据类型 自动推断，支持多行字符串 严格类型，字符串必须双引号
引用 支持锚点 & 和别名 * 不支持
工具链兼容性 部分工具需额外解析器 原生支持，解析速度快
YAML 编写避坑指南：
  • 缩进一致性： 必须使用空格，禁止使用 Tab。推荐 2 空格缩进。
  • 字符串引号： 包含特殊字符（如 :、#）时，必须用双引号包裹。
  • 布尔值陷阱： yes、no、true、false 会被自动解析为布尔类型，字符串应加引号。
  • 多行字符串： 使用 |（保留换行）或 >（折叠换行）处理长描述。

2.5 YAML 与 JSON 互转示例

以下展示同一段 OpenAPI 文档的 YAML 和 JSON 写法对比，帮助理解两种格式的映射关系。

# YAML 格式
openapi: "3.0.3"
info:
  title: "消息契约示例"
  version: "1.0.0"
paths:
  /send:
    post:
      summary: "发送消息"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
components:
  schemas:
    Message:
      type: object
      properties:
        id:
          type: string
        payload:
          type: string
// JSON 格式（等价）
{
  "openapi": "3.0.3",
  "info": {
    "title": "消息契约示例",
    "version": "1.0.0"
  },
  "paths": {
    "/send": {
      "post": {
        "summary": "发送消息",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Message"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "payload": {
            "type": "string"
          }
        }
      }
    }
  }
}
常见故障点： 在中间件消息契约环境中，YAML 缩进错误是导致 OpenAPI 文档解析失败的首要原因。建议使用支持 YAML 语法检查的编辑器（如 VS Code + YAML 插件），并在 CI/CD 流程中加入 swagger-cli validate 或 openapi-generator validate 步骤。

2.6 本章小结

OpenAPI 规范从 Swagger 2.0 演进到 3.1.0，核心结构围绕 openapi、info、paths、components 四个顶层对象展开。YAML 以其高可读性成为编写消息契约的首选格式，但需注意缩进、引号、布尔值等语法细节。掌握这些基础，是后续配置中间件消息契约环境、进行故障排查的基石。

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