OpenAPI 发布前检查清单：不只要 YAML 能打开

OpenAPI 文件最容易出现一种假象：YAML 没有语法错误，Swagger UI 也能显示，于是大家默认文档可以交付。直到生成客户端、导入网关或让另一组开发者接入，才发现路径参数漏了 required: true，两个接口用了相同的 operationId，或者 $ref 指向根本不存在的 Schema。

OpenAPI / Swagger 结构检查工具会在浏览器本地解析 YAML 或 JSON，整理接口清单，并检查一批高频结构问题。它适合写文档和提交代码前快速预检，但不能替代项目 CI 中锁定版本的完整校验器。

第一步不是看接口，而是确认规范版本

常见根节点是：

openapi: 3.1.0

或旧版：

swagger: "2.0"

OpenAPI 3.0、3.1 和 Swagger 2.0 对请求体、服务器、Schema 和 nullable 等写法并不完全相同。把 3.0 的习惯直接搬到 3.1，或者在 Swagger 2.0 中使用 3.x 的 requestBody，都可能让不同工具给出不一致结果。

版本明确后，再检查 info.title 和 info.version。这里的 info.version 是 API 自身版本，不是 OpenAPI 规范版本。它应该能帮助使用者判断契约是否变化，而不是长期写成随意的 1.0。

paths 中最值得先检查的四件事

1. 路径必须与参数声明对应

路径：

/orders/{orderId}:

需要有同名参数：

- name: orderId
  in: path
  required: true
  schema:
    type: string

orderId 与 id 不是同一个名字。路径参数也必须是必填，因为没有值就无法组成请求 URL。

路径级参数可被该路径下多个操作复用，操作级参数则只对当前方法生效。检查时要把两处合并理解，不能只搜索当前 get 或 post 内部。

2. operationId 应稳定且唯一

很多客户端生成器会把 operationId 直接变成函数名。重复值可能覆盖代码，缺少值则由生成器自行猜测，改一次路径就可能让调用方法整体改名。

好的 operationId 通常简短、稳定、可读：

getOrder
createOrder
cancelOrder

不要把版本号、临时团队名或会频繁变化的 URL 细节塞进去。重命名 operationId 可能是破坏性变更，应和代码发布一起管理。

3. responses 不能只有“出错再说”

每个操作都应有 responses。至少要明确成功状态码和常见失败情况：

responses:
  "200":
    description: 查询成功
  "404":
    description: 订单不存在

只写 default 虽然在部分场景合法，但对客户端生成和接口测试帮助有限。创建资源常用 201，异步受理常用 202，无正文成功可用 204。状态码要与真实服务一致，不能为了让文档通过检查随便补一个 200。

响应对象的 description 也很重要。它不需要写长篇文档，但至少说明这个响应代表什么。

4. summary 与 tags 决定文档是否能用

summary 不是强制字段，却直接影响接口列表可读性。只有路径和方法时，POST /orders/{id}/actions 很难让接入者立即理解用途。

标签应围绕稳定业务域，例如 Orders、Products、Payments，而不是按开发者姓名或本周需求分组。标签太多会让文档导航比没有标签更混乱。

$ref 通过不等于引用树完整

文档内引用常见形式：

$ref: "#/components/schemas/Order"

它本质上是 JSON Pointer。路径中的 / 和 ~ 有转义规则，大小写也必须完全一致。重命名 Schema 后忘记更新引用，是常见错误。

外部引用可能是：

$ref: "./schemas/order.yaml"

或一个 HTTPS 地址。网页工具不会擅自下载它们，因为相对路径依赖项目目录，远程地址可能需要认证，也可能暴露内部网络。

项目级校验应从仓库根目录运行，解析完整引用树，并确保 CI 使用的文件与发布文档来自同一次构建。

Schema 能通过，也可能不适合客户端

OpenAPI 3.1 与 JSON Schema 2020-12 更接近，但客户端生成器支持程度并不统一。下面这些结构尤其要用实际目标生成器测试：

• oneOf、anyOf、allOf 的组合；
• discriminator；
• nullable 与 type: ["string", "null"]；
• additionalProperties；
• 递归 Schema；
• 日期、金额、整数范围和自定义 format；
• readOnly、writeOnly；
• 多种媒体类型和文件上传。

可以把单个 Schema 交给 JSON Schema 校验工具验证样本，但最终还要生成一次真实客户端或服务端桩代码，检查类型是否符合预期。

为什么浏览器预检不能代替 CI

浏览器工具适合即时反馈和接口清单整理，CI 校验则负责可重复、可阻断的项目规则。

可靠的流水线通常包括：

1. YAML/JSON 语法检查；
2. 官方规范 Schema 或成熟解析器校验；
3. Spectral 等团队规则检查；
4. 外部 $ref 完整解析；
5. 与上一版本做 breaking change 检查；
6. 生成文档和客户端；
7. 用契约测试验证真实服务响应。

常用项目工具包括 Swagger Parser、Redocly CLI、Spectral 和 openapi-diff。关键不是堆很多命令，而是锁定版本，并让本地与 CI 使用同一配置。

cURL 草稿为什么不能直接复制到生产

从规范生成的 cURL 通常只能确定方法、服务器和路径。真实请求还缺少：

• 路径参数实际值；
• 查询参数；
• Authorization 或 Cookie；
• 真实 JSON 请求体；
• 幂等键和追踪 Header；
• 客户端证书；
• 测试、预发布与生产环境差异。

把生成结果当作请求骨架，先在测试环境补齐。不要把规范中看似示例的 Token 当成真实凭证，也不要直接对生产接口执行写操作。

一套实际检查顺序

先在本地结构检查中清掉解析错误、断开的本地 $ref、路径参数错误和重复 operationId。导出接口 CSV，让产品、前端、后端和测试共同确认接口范围。

然后在项目仓库运行完整校验器，解析外部引用并执行团队规则。对关键请求和响应准备真实示例，生成一次目标语言客户端。

最后把规范版本、服务部署和文档发布绑定到同一流水线。OpenAPI 最有价值的地方不是“展示一份漂亮文档”，而是让不同角色使用同一个可验证的接口契约。