2. OpenAPI 规范基础：版本演进、核心结构与语法
OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的行业标准，也是本课程中定义消息队列任务接口契约的核心工具。理解其版本演进、核心结构与 YAML/JSON 语法，是后续进行契约覆盖度分析的前提。
2.1 版本演进与关键差异
OpenAPI 规范经历了多个版本迭代，目前主流版本为 2.0（Swagger）和 3.0.x。本课程基于 OpenAPI 3.0.3 进行讲解，因其在组件复用、请求体描述、回调支持等方面更为完善。
| 特性 | Swagger 2.0 | OpenAPI 3.0.x |
|---|---|---|
| 根对象 | swagger: "2.0" |
openapi: "3.0.3" |
| 请求体描述 | 通过 body 参数 + in: body |
独立 requestBody 对象，支持多 Content-Type |
| 组件复用 | definitions、parameters、responses |
统一 components 对象，包含 schemas、parameters、requestBodies、responses、headers 等 |
| 回调支持 | 不支持 | 支持 callbacks，用于异步事件 |
| 链接与状态码 | 仅支持 HTTP 状态码 | 支持 links 描述状态间关系，支持 anyOf/oneOf |
| 安全定义 | securityDefinitions |
components/securitySchemes |
版本选择建议： 对于消息队列任务接口，建议使用 OpenAPI 3.0.x。其
requestBody 对象能更清晰地描述消息体结构，components 机制可复用队列配置、消息 Schema，减少冗余。
2.2 核心结构：info、paths、components
一个标准的 OpenAPI 文档由三个核心顶层字段构成：info、paths、components。它们共同定义了 API 的元信息、端点路径与可复用组件。
2.3 YAML/JSON 语法与选择
OpenAPI 文档支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释支持好，成为编写契约的首选；JSON 则常用于程序解析与传输。
2.3.1 语法对比
| 特性 | YAML | JSON |
|---|---|---|
| 可读性 | 高，缩进表示层级 | 中等，大量花括号与引号 |
| 注释 | 支持 # 注释 |
不支持 |
| 多行字符串 | 支持 | 和 > |
需转义 \n |
| 数据类型 | 自动推断，支持布尔、数字、null | 严格区分字符串、数字、布尔 |
| 引用 | 支持锚点 & 和别名 * |
不支持 |
| 适用场景 | 手写契约、设计阶段 | 程序生成、API 网关配置 |
2.3.2 消息队列任务接口示例（YAML）
以下是一个描述消息队列任务发布接口的 OpenAPI 3.0.3 片段，展示了核心结构的使用：
openapi: "3.0.3"
info:
title: 消息队列任务接口
version: "1.0.0"
description: 用于发布和消费异步任务的消息队列 API
paths:
/tasks/publish:
post:
summary: 发布任务到队列
operationId: publishTask
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskMessage'
responses:
'202':
description: 任务已接受
content:
application/json:
schema:
$ref: '#/components/schemas/TaskAcceptedResponse'
'400':
description: 请求格式错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
TaskMessage:
type: object
required:
- taskId
- payload
properties:
taskId:
type: string
description: 任务唯一标识
payload:
type: object
description: 任务数据负载
priority:
type: integer
enum: [1, 2, 3]
description: 优先级（1 最高）
delaySeconds:
type: integer
default: 0
description: 延迟执行秒数
TaskAcceptedResponse:
type: object
properties:
taskId:
type: string
status:
type: string
example: "queued"
ErrorResponse:
type: object
properties:
code:
type: string
message:
type: string
关键点：
$ref引用components/schemas中的定义，实现 Schema 复用。requestBody明确指定了 Content-Type 为application/json，并引用了TaskMessage结构。- 响应状态码
202表示异步接受，符合消息队列语义。
2.4 核心结构关系图
下图展示了 OpenAPI 文档中 info、paths、components 之间的引用关系，以及它们如何共同描述一个消息队列任务接口：
常见陷阱：
- 缩进错误： YAML 对缩进敏感，使用空格而非 Tab，层级不一致会导致解析失败。
- 引用循环：
$ref不能形成循环引用，否则工具会报错。 - 版本声明： 必须显式声明
openapi: "3.0.3"，否则解析器可能默认使用 Swagger 2.0。