OpenAPI Diff

这个对比工具检查什么——以及“破坏性”到底是什么意思

一项变更之所以是破坏性的，是因为一个严格按旧规范写对的客户端，不改自己一行代码，就可能在新规范下失败。页面上的每一个判断都由这个定义驱动。删除路径或操作是破坏性的，因为现有的调用无处可去。删除响应状态码——尤其是 2xx——是破坏性的，因为客户端的错误处理正是围绕旧的状态码集合编写的。新增一个必填参数或必填的请求属性是破坏性的，因为昨天的合法请求会突然被拒绝。改变字段的类型或格式是破坏性的，因为解析器、校验器和生成的 SDK 都按声明的类型工作。移除枚举值是破坏性的，因为客户端可能仍会发送它，或者保存着无法再解释的数据。其余一切——新端点、可选参数、新的响应字段、新的枚举值、新的状态码——都被报告为非破坏性：旧客户端继续可用，哪怕它暂时还用不上新能力。

比较是结构层面的，不是文本层面的。在比较之前，两份文档都会被归一化为同一个模型：每条路径和每个操作、按名称与位置索引的参数、请求正文与每个响应都被归约为一个模式签名——由类型、格式、属性名、必填列表和枚举值递归构建的确定性摘要，本地 $ref 引用会被展开。正因如此，调整键的顺序、重排空白或重写所有描述文字都会得到一个空的对比结果：这些都不改变契约。也正因如此，埋在被引用模式三层深处的一处变更仍然会被找到——签名展开的是引用本身，而不是仅仅比较它的名字。

这里接受两种输入形态，因为生态里两种都有人发布：先按 JSON 尝试解析，失败时再按 YAML 解析——大多数手写的 OpenAPI 文档用的正是 YAML。Swagger 2.0 文档同样可用，包括它的 in: body 参数和每个响应自带的模式。这里刻意没有在线拉取、也没有上传：像处理 HAR 抓取文件 一样粘贴文档或拖入文件即可，而且对比是在你按下按钮时才运行——而不是每次按键都运行——所以粘贴两份很大的规范也不会卡顿。

把结果当作发布门禁来用，而不是装饰。在评审中，破坏性列表就是议程：每一项都需要修复、提升版本号、给出弃用窗口，或者留下一份“这次破坏是有意为之且已通知”的书面决定。非破坏性列表就是变更日志的草稿。把对比结果导出为 JSON，可以把这份决定归档在版本旁边；可复制的摘要可以直接放进拉取请求——这与对待 webhook 契约变更是同一套纪律：一份被悄悄改动的负载会同时破坏每一个订阅方。

诚实的限制，明确说出来。这个对比工具比较的是声明过的契约：它看不见规范没有声明的行为，例如字段类型不变但含义变了、新增的业务规则、更紧的限流，或者客户端（不明智地）在解析的错误消息文本。工具会跟随本地引用并在有限深度内比较模式，因此病态的深层嵌套或互相递归的模式会被摘要化，而不是无限展开下去。而且，零破坏性变更的对比结果并不能保证升级一定安全——它证明的是文档化的契约没有变，这恰恰是部署之前值得拥有的证据。