对比线上 API 响应与 OpenAPI 规范

目标

OpenAPI 文档如果从来没人拿生产流量去校验，它就只是文档而不是契约。本食谱用 curl 加 jq 把真实响应与声明的 schema 逐字段对照，把所有不一致打印成证据，让“规范悄悄过时”这类问题在客户端崩溃之前被发现。

步骤要点

1. 下载 openapi.json，用 jq 解析目标路径 200 响应的 $ref，定位到具体的 components/schemas 定义。
2. 抓取线上接口的真实响应存为 live.json，先打印一两个关键字段建立直观印象。
3. 分别提取规范声明的字段列表与响应实际字段列表，排序后 diff，找出单侧独有的字段。
4. 对两侧共有的字段核对枚举取值与类型：把规范 enum 与线上值放在同一行打印，漂移一眼可见。
5. 把手工检查固化成脚本并接入 CI，让规范漂移变成构建失败而不是用户工单。

排错提示

$ref 指向嵌套 allOf 时先用 jq 递归解引用，或等手工 diff 证明规范文件本身没问题后交给 schemathesis；字段随特性开关变化就分别在开关开关两种状态下采样，并在规范里用 oneOf 或可空字段记录两种变体；规范用 3.0 的 nullable 语法而校验器按 3.1 解析时，先做一次 jq 转换或固定校验器版本。

适用边界

单条响应只能证明该响应符合规范，要覆盖多种状态包括错误响应才有说服力；请求参数与请求头不在响应体 diff 的范围内，需要从 paths 段单独校验。

代码示例

# Extract declared enum for a field
jq -r '.components.schemas.Order.properties.status.enum' openapi.json
# → ["pending", "shipped"]

# Read the value production actually returns
jq -r '.status' live.json
# → "partially_shipped"   <-- spec drift, mobile app crashes