3. OpenAPI 规范基础：核心概念、格式选择与本地工具搭建
在缓存一致性治理中，OpenAPI 契约是连接设计、开发、测试与运维的“单一事实来源”。本章将系统讲解 OpenAPI 3.0/3.1 的核心概念、YAML 与 JSON 的选型策略，以及 Swagger Editor 与 Swagger UI 的本地搭建方法，为后续的契约落地打下坚实基础。
3.1 OpenAPI 3.0/3.1 核心概念
OpenAPI 规范（原 Swagger 规范）是一种用于描述 HTTP API 的接口描述语言。它通过结构化的文档定义 API 的端点、请求参数、响应格式、认证方式等，使人和机器都能理解 API 的能力。OpenAPI 3.0 于 2017 年发布，3.1 于 2021 年发布，后者完全兼容 JSON Schema 2020-12。
3.1.1 核心对象模型
OpenAPI 文档的顶层结构由以下几个核心对象组成：
| 对象 | 说明 | 3.0/3.1 差异 |
|---|---|---|
| openapi | 规范版本号，如 "3.0.3" 或 "3.1.0" | 3.1 要求使用语义化版本号 |
| info | API 元信息：标题、版本、描述、联系人 | 无显著差异 |
| servers | API 的基础 URL 列表，支持变量替换 | 3.1 支持相对 URL |
| paths | API 的所有端点及其操作（GET/POST/PUT/DELETE 等） | 无显著差异 |
| components | 可复用的 schema、参数、响应、请求体等 | 3.1 支持 JSON Schema 2020-12 全部关键字 |
| security | 全局安全方案声明 | 无显著差异 |
| tags | 用于分组端点的标签 | 无显著差异 |
3.1.2 路径与操作描述
每个路径（path）下可以定义多个操作（operation），每个操作包含：
- parameters：路径参数、查询参数、请求头参数
- requestBody：请求体结构（3.0 中为 body 参数）
- responses：每个状态码对应的响应结构
- security：操作级别的安全要求
- tags：操作所属的标签
parameters 定义缓存键（cacheKey），使用 responses 定义失效成功/失败的返回结构，确保客户端与缓存治理层之间的契约清晰。
3.2 YAML 与 JSON 格式选择
OpenAPI 规范支持 YAML 和 JSON 两种序列化格式。两者在语义上完全等价，但在可读性、编写效率和工具支持上存在差异。
| 维度 | YAML | JSON |
|---|---|---|
| 可读性 | 高，缩进结构清晰，支持注释 | 中，括号嵌套较多，不支持注释 |
| 编写效率 | 高，语法简洁，适合手写 | 低，需要严格括号和逗号 |
| 工具支持 | 广泛，Swagger Editor 默认使用 YAML | 广泛，几乎所有编程语言都有原生解析器 |
| 复杂结构 | 锚点（anchor）和别名（alias）可复用节点 | 无原生复用机制，需借助 $ref |
| 推荐场景 | 契约编写、代码审查、文档生成 | 程序生成、API 网关配置、CI/CD 流水线 |
在实际项目中，推荐采用“YAML 编写 + JSON 交付”的策略：开发阶段使用 YAML 维护契约源码，CI/CD 阶段通过工具（如 swagger-cli）将 YAML 转换为 JSON，用于 API 网关和测试框架。
3.3 Swagger Editor 与 Swagger UI 本地搭建
Swagger Editor 和 Swagger UI 是 OpenAPI 生态中最常用的两个工具。Editor 用于编写和预览契约，UI 用于渲染和交互式调试。本地搭建可以避免网络延迟，并支持离线开发。
3.3.1 搭建方式对比
| 方式 | 适用场景 | 启动命令 |
|---|---|---|
| Docker 部署 | 团队统一环境、CI/CD 集成 | docker run -p 8080:8080 swaggerapi/swagger-editor |
| npm 本地安装 | 个人开发、离线使用 | npm install -g swagger-editor-live |
| 静态文件部署 | 内网环境、安全要求高 | 下载 dist 目录，用 nginx 或 http-server 托管 |
3.3.2 Docker 快速搭建（推荐）
Docker 方式最为简洁，适合团队快速启动：
# 启动 Swagger Editor
docker run -d --name swagger-editor -p 8080:8080 swaggerapi/swagger-editor
# 启动 Swagger UI（需挂载 OpenAPI 文件）
docker run -d --name swagger-ui -p 8081:8080 \
-e SWAGGER_JSON=/app/openapi.yaml \
-v /path/to/your/openapi.yaml:/app/openapi.yaml \
swaggerapi/swagger-ui启动后，访问 http://localhost:8080 即可使用 Editor，访问 http://localhost:8081 查看 UI 渲染效果。
3.3.3 本地 npm 安装
对于个人开发环境，npm 安装更灵活：
# 安装 swagger-editor-live（支持热重载）
npm install -g swagger-editor-live
# 启动，指定 OpenAPI 文件目录
swagger-editor-live --port 8080 --watch ./api-specsSwagger UI 的 npm 包为 swagger-ui-dist，可结合 Express 或 http-server 使用：
npm install -g http-server swagger-ui-dist
cp -r node_modules/swagger-ui-dist ./swagger-ui
cd swagger-ui
http-server -p 80813.4 核心概念关系图
下图展示了 OpenAPI 文档的核心对象及其关系，帮助理解契约的结构层次：
3.5 本地工具工作流
下图展示了 Swagger Editor 与 Swagger UI 在本地开发环境中的协作流程：