OpenAPI 变更对比
OpenAPI Diff
比较两份 OpenAPI 文档，把破坏兼容的变更和纯粹新增的分开列。
比较一份 OpenAPI 文档的两个版本，把改动分成破坏性的和纯新增的。它用的规则写在页面上：如果旧文档接受的请求现在可能被拒绝，或者它承诺的响应变成了现有客户端无法再处理的，这个改动就是破坏性的。
旧文档
拖入旧版本
只在这个标签页里读取。
新文档
拖入新版本
只在这个标签页里读取。
破坏兼容
8
向后兼容
7
判定
需要升主版本号
GET /pets
- 破坏兼容`in: query` 参数 `limit` 现在是必填的了。
- 新增新增了一个可选的 `in: query` 参数 `sort`。
- 修改摘要或说明变了。
GET /pets · responses["200"].content["application/json"]
- 破坏兼容`[].id`的类型从 integer 变成了 string。
- 破坏兼容属性 `[].name` 现在是可选的了。
- 破坏兼容`[].status`的 enum 里多了 "pending"。
- 新增新增了一个可选属性 `[].owner`。
GET /pets/{petId} · responses["200"].content["application/json"]
- 破坏兼容`id`的类型从 integer 变成了 string。
- 破坏兼容属性 `name` 现在是可选的了。
- 破坏兼容`status`的 enum 里多了 "pending"。
- 新增新增了一个可选属性 `owner`。
GET /pets/{petId}
- 破坏兼容`404` 响应没了。
DELETE /pets/{petId}
- 新增新增了这个操作。
components.schemas.Owner
- 新增新增了一个 schema。
info.version
- 修改`1.0.0` → `2.0.0`
什么算破坏兼容
一句话说：旧文档原本接受的请求现在可能被拒，或者旧文档承诺的响应现有客户端已经处理不了。所以：删掉路径、操作、响应码、媒体类型或响应属性；加上必填参数或必填的请求属性；可选变必填；类型变化；删掉请求 enum 的值；加上响应 enum 的值（客户端的 switch 里没有对应的 case）；以及响应属性从必填变可选——这些都算破坏兼容。反方向的改动，以及说明、标签、operationId 和 deprecated 标记的改动，都是兼容的。
- · schema 是先跟着文档内部的
$ref解开再比的，所以只给组件改个名字不算变更。路径参数也按位置而不是按名字对上。 - ·
oneOf·anyOf·not的内部是整块比的，不一样就报成破坏兼容，这里不去推理里面的含义。 - · 指向另一个文件的
$ref不会跟进去。请先把这些文件打包成一份。
要检查单独一份文档，可以用 OpenAPI 检查。
怎么用
把旧文档和新文档并排放好
两边都可以是 JSON 或 YAML。两者都在这个标签页里解析，所以一份未发布的规范不会离开你的机器。
读结论
破坏性改动的数量、新增的数量，以及这对版本号意味着什么：升主版本、升次版本，或者因为契约没变而什么都不用动。
筛出破坏性的那些并读一遍
按操作分组，每条带着改了什么。Markdown 副本的形状适合放进 pull request 描述。
常见问题
为什么给响应的枚举加一个值是破坏性的？
因为现有客户端有一个没有为它准备分支的 switch。给*请求*的枚举加值是安全的——服务端比以前接受得更多；给响应的枚举加值，是给客户端发送它们从未被告知的东西。方向决定一切。
我重命名了一个组件，它报告没有改动。
正确。schema 是在跟随 `$ref` 之后比较的，所以一个形状相同、只是改了名的组件是同一份契约。`components` 里的名字是内部的；客户端看到的是解析后的形状。
响应里一个必填属性变成可选真的是破坏性的吗？
是的，从客户端的角度看。它被承诺过这个字段总会在，它的代码无条件地读它；改成可选意味着服务端现在可以省略它。必填和可选在请求和响应之间方向互换，这正是人们弄反的地方。
它怎么处理 `oneOf` 和 `anyOf`？
作为一个整体比较，只要有任何不同就报告为破坏性的。推理一个联合是不是另一个的超集，是这里有意不去尝试的判定过程；一个你可以驳回的假「破坏性」，好过一个你无法驳回的假「安全」。
可以从这些接进来
JSON 对比
JSON Diff
按结构比较两份 JSON，忽略键的顺序，报出新增、删除和改动的路径。
OpenAPI 检查
OpenAPI Linter
检查 OpenAPI 文档里缺失的响应、没人用的 schema、指不到东西的引用，以及别的会弄坏代码生成器的毛病。
Semver 版本范围测试
Semver Range Tester
看哪些版本落在某个范围里，比较两个版本，并把一串版本按优先级排好序。
JSON 格式化与校验
JSON Formatter & Validator
把 JSON 美化成缩进形式或压成一行，校验语法并直接指出出错的行和列。
接下来
这些工具吃得下当前工具的产出，结果可以直接送过去。
JSON 对比
JSON Diff
按结构比较两份 JSON，忽略键的顺序，报出新增、删除和改动的路径。
JSON Schema 校验
JSON Schema Validator
用 JSON Schema 校验文档，每一处失败都带上它在实例里的路径。
OpenAPI 检查
OpenAPI Linter
检查 OpenAPI 文档里缺失的响应、没人用的 schema、指不到东西的引用，以及别的会弄坏代码生成器的毛病。
Semver 版本范围测试
Semver Range Tester
看哪些版本落在某个范围里，比较两个版本，并把一串版本按优先级排好序。
JSON ⇄ CSV 互转
JSON ⇄ CSV
把嵌套 JSON 按点路径列名拍平成列，或者从表格重新拼回对象。
JSON 格式化与校验
JSON Formatter & Validator
把 JSON 美化成缩进形式或压成一行，校验语法并直接指出出错的行和列。