01
旧版放左，新版放右
风险按旧版客户端判断。交换两侧会先显示预览；确认后报告过期，撤销可恢复两份输入和原结果。
API 契约工具
OpenAPI 差异对比上线前看清影响
分别粘贴旧版和新版规范；确认方向后手动运行对比。
OpenAPI 差异对比
旧版规范
新版规范
变更报告
两份规范都在当前浏览器内处理，不主动发送 API 请求。
比较选项
范围：仅跟踪请求端点、参数、请求体与响应；静态报告不能证明运行时兼容。
粘贴两份规范后再比较。
准备发布接口变更时，OpenAPI 差异对比能把文本行号转成调用方看得懂的影响：删掉哪个端点、增加了哪个必填值、响应少了哪个字段。
这也是接口文档差异对比，但结果不是简单的红绿文本。OpenAPI 规范对比会把证据不足的 API 契约变更留在“需复核”，避免误称兼容。
为什么使用 OpenAPI 差异对比
按旧版调用方的方向看风险
OpenAPI 差异对比从旧契约读到新契约。删除响应字段与新增端点分开标记，评审可以先处理可能让现有客户端失效的改动。
忽略范围能追溯
每行填写一个精确路径后，该路径在两份规范中都被排除。报告仍列出被忽略的路径，团队能复核覆盖范围，而不必猜测通配符匹配了什么。
对比前值得确认的三件事
02
路径必须精确匹配
例如输入 /internal/health，一行一个完整 OpenAPI 路径。它不是正则或 JSON Pointer；更改后要重新运行才能导出。
03
筛选不裁剪报告
风险筛选只改变屏幕上显示的条目。复制的 JSON 与下载的 Markdown 仍包含最新完整报告和被忽略路径。
从端点到响应的影响证据
端点与方法
删除旧路径或 HTTP 方法会列为潜在破坏项，新增端点单独列出；OpenAPI 破坏性变更不再淹没在文本差异中。
参数与字段
新增必填参数、必填请求属性、删除的响应状态和响应字段会被逐项定位；可解析的简单 Schema 类型与枚举变化也会提示。
可交接的完整报告
每条记录都有方法、路径、规则及变化前后值。JSON 适合程序审阅，Markdown 适合评审记录；只有新鲜完整结果可导出。
静态规范分析的边界
- 不抓取远程地址
- 只接受粘贴的 JSON 或 YAML；不请求规范 URL，不调用目标 API，也不上传两侧输入。
- 只忽略精确路径
- 路径必须与 OpenAPI 的 path 键完全相同。通配符、正则、回调路由不在本次比较范围。
- 不完整就阻断结论
- 外部 $ref、未支持的方言、callback 与 webhook 会阻止生成新的风险报告，避免把没解析的地方算成安全。
- 不证明运行时兼容
- 静态规范不知道服务器是否照规范执行，也不知道客户端依赖了哪些字段；发布前仍需消费者测试。
OpenAPI 差异对比常见问题
支持哪些类型的 API 规范文件？
支持 Swagger 2.0 与 OpenAPI 3.0、3.1 的 JSON 或 YAML 文本。跨大版本迁移的语义变化仍需人工复核；GraphQL 与 Postman 集合不在此页范围。
什么是破坏性变更（Breaking Change）？
破坏性变更指旧版合法调用在新契约下可能失效，例如端点删除、参数变为必填或响应字段消失。OpenAPI 差异对比把这些变化列为潜在破坏项，而非上线保证。
工具能自动检测 Schema 类型吗？
能检查可解析的简单 Schema 类型、枚举和属性变化。复杂组合 Schema、远程引用或不完整规范不能给出完整兼容结论。
影响分析报告包含哪些内容？
报告按端点列出风险类别、规则、JSON Pointer 与前后值，包含忽略路径记录。类别筛选只改变视图，不影响导出内容。
我的 API 规范数据安全吗？
规范只在当前浏览器内处理，不主动发起 API 请求或上传。关闭页面后工具不保存历史；若要留档请自己下载报告。
这次比较有帮助吗？