3. OpenAPI 规范入门：OpenAPI 3.0 核心概念
OpenAPI 规范（原 Swagger 规范）是定义 HTTP API 接口描述的标准格式。在消息队列任务契约开发中，OpenAPI 3.0 用于精确描述生产端与消费端之间的 HTTP 交互接口，包括消息投递路径、请求参数、响应结构等。本节将围绕其核心概念、文件格式定义及可视化工具展开。
3.1 核心概念：路径、方法、请求体、响应体
OpenAPI 3.0 文档的核心由四个基本元素构成，它们共同定义了 API 的完整交互契约：
| 核心元素 | 说明 | 消息队列场景示例 |
|---|---|---|
| 路径（Path） | API 的端点 URL 模板，如 /v1/queues/{queueName}/messages |
定义消息队列的投递入口 |
| 方法（Method） | HTTP 动词，如 GET、POST、PUT、DELETE | POST 用于发送消息，GET 用于消费消息 |
| 请求体（Request Body） | 客户端发送给服务端的数据结构，通常为 JSON | 消息体内容、消息属性、路由键等 |
| 响应体（Response Body） | 服务端返回给客户端的数据结构及状态码 | 消息 ID、投递状态、错误信息 |
关键理解： 路径 + 方法 = 操作标识；请求体 + 响应体 = 数据契约。四者缺一不可，共同构成一个完整的 API 操作定义。
3.2 YAML / JSON 格式定义
OpenAPI 3.0 支持 YAML 和 JSON 两种序列化格式。YAML 因其可读性高、注释友好，成为编写 API 规范的首选；JSON 则更适用于程序解析和传输。两者可无损互转。
3.2.1 文档顶层结构
一个标准的 OpenAPI 3.0 文档包含以下顶层字段：
- openapi：版本号，固定为
3.0.3 - info：API 元信息（标题、版本、描述）
- servers：服务器地址列表
- paths：所有 API 路径的定义
- components：可复用的 schema、参数、响应等
3.2.2 消息队列任务契约示例（YAML）
openapi: "3.0.3"
info:
title: 消息队列任务契约
version: "1.0.0"
description: 定义消息生产与消费的 HTTP 接口规范
servers:
- url: https://mq.example.com/api/v1
description: 生产环境消息队列服务
paths:
/queues/{queueName}/messages:
post:
summary: 发送消息到指定队列
operationId: sendMessage
parameters:
- name: queueName
in: path
required: true
schema:
type: string
description: 目标队列名称
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageRequest'
responses:
'201':
description: 消息发送成功
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageResponse'
'400':
description: 请求参数错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
SendMessageRequest:
type: object
required:
- body
- routingKey
properties:
body:
type: string
description: 消息体内容
routingKey:
type: string
description: 路由键
headers:
type: object
description: 消息头（可选）
SendMessageResponse:
type: object
properties:
messageId:
type: string
description: 消息唯一标识
status:
type: string
enum: [queued, delivered]
ErrorResponse:
type: object
properties:
code:
type: integer
message:
type: string
格式要点： YAML 使用缩进表示层级（2 空格为标准），
$ref 引用可复用组件，避免重复定义。路径参数使用花括号 {queueName} 表示。
3.2.3 JSON 格式等价表示
上述 YAML 文档可转换为 JSON 格式，结构完全一致：
{
"openapi": "3.0.3",
"info": {
"title": "消息队列任务契约",
"version": "1.0.0",
"description": "定义消息生产与消费的 HTTP 接口规范"
},
"servers": [
{
"url": "https://mq.example.com/api/v1",
"description": "生产环境消息队列服务"
}
],
"paths": {
"/queues/{queueName}/messages": {
"post": {
"summary": "发送消息到指定队列",
"operationId": "sendMessage",
"parameters": [
{
"name": "queueName",
"in": "path",
"required": true,
"schema": { "type": "string" },
"description": "目标队列名称"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/SendMessageRequest" }
}
}
},
"responses": {
"201": {
"description": "消息发送成功",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/SendMessageResponse" }
}
}
}
}
}
}
},
"components": {
"schemas": {
"SendMessageRequest": {
"type": "object",
"required": ["body", "routingKey"],
"properties": {
"body": { "type": "string", "description": "消息体内容" },
"routingKey": { "type": "string", "description": "路由键" },
"headers": { "type": "object", "description": "消息头（可选）" }
}
}
}
}
}
3.3 Swagger Editor 使用
Swagger Editor 是 OpenAPI 规范的官方可视化编辑器，支持实时预览、语法校验和代码生成。在消息队列任务契约开发中，它帮助团队快速验证接口定义的正确性。
3.3.1 核心功能
| 功能 | 说明 | 使用场景 |
|---|---|---|
| 实时预览 | 左侧编辑 YAML/JSON，右侧即时渲染为交互式 API 文档 | 快速验证路径、参数、响应结构 |
| 语法校验 | 自动检测格式错误、必填字段缺失、引用断裂 | 避免因格式问题导致契约无效 |
| 代码生成 | 支持生成服务端 Stub、客户端 SDK（Java、Python、Go 等） | 从契约自动生成消息队列客户端代码 |
| 导入/导出 | 支持从 URL 导入规范，导出为 YAML/JSON | 团队协作共享契约文件 |
3.3.2 使用流程
- 打开编辑器：访问 Swagger Editor 在线版（editor.swagger.io）或本地 Docker 部署
- 编写或粘贴规范：在左侧编辑区写入 YAML/JSON 内容
- 观察预览区：右侧自动渲染为可折叠的 API 文档，点击路径可展开详情
- 修复错误：编辑器顶部会显示红色错误提示，点击可定位到问题行
- 导出契约：通过 File → Save as YAML/JSON 导出最终规范文件
常见陷阱： Swagger Editor 对缩进敏感，YAML 中混用 Tab 和空格会导致解析失败。建议统一使用 2 空格缩进，并在编辑器中开启“显示空格”功能。
3.4 小结
本节介绍了 OpenAPI 3.0 的四个核心概念（路径、方法、请求体、响应体），展示了 YAML 和 JSON 两种格式的定义方法，并说明了 Swagger Editor 的使用流程。掌握这些基础后，即可开始为消息队列任务编写正式的接口契约文档。