OpenAPI 差异对比与破坏性变更检查器
对比两份 OpenAPI 或 Swagger 规范，标出 API 的破坏性变更
输入
基线规范
粘贴 JSON 或 YAML，上传文件，或导入 URL。
候选规范
粘贴 JSON 或 YAML，上传文件，或导入 URL。
结果
添加基线规范和候选规范，然后选择“比较”。
详情
尚未比较。
OpenAPI Diff 会检查什么？
OpenAPI Diff 按语义而非文本来比较基线和候选 API 规范。它按方法和路径匹配操作（因此 /users/{id} 与 /users/{userId} 视为同一个端点），解析内部 $ref 引用，并报告每一处契约变更及其所属操作、位置、变更前后的值，以及对客户端的影响。支持 JSON 或 YAML 格式的 Swagger 2.0、OpenAPI 3.0 和 OpenAPI 3.1，其中 Swagger 2.0 会先被规范化为 OpenAPI 3 的结构。
使用方法
- 1.粘贴、上传或导入基线规范（客户端当前使用的版本）。
- 2.添加候选规范（拟发布的版本）。
- 3.选择“比较”。
- 4.查看“破坏性”“警告”和“兼容”标签页，并按方法或范围筛选。
- 5.选择一项变更，查看变更前后的值及其重要性。
- 6.复制破坏性变更用于拉取请求，或下载 Markdown 或 JSON 报告用于 CI。
变更如何分类
请求和响应按相反的方向来判断。在请求一侧（客户端发送的内容），任何收窄可接受范围的变更都属于破坏性变更：新增必填参数或属性、移除枚举值、更改类型或格式、降低最大值或提高最小值、新增正则模式，或移除内容类型。在响应一侧（客户端接收的内容），任何移除或放宽客户端所读取内容的变更都属于破坏性变更或警告：移除属性或成功状态码、更改类型、新增枚举值，或必填属性变为可选。移除端点、新增认证、更改安全方案以及新增 OAuth 作用域都属于破坏性变更。对描述、摘要、标题和示例的修改属于文档变更，除非你将其开启，否则默认隐藏。
限制与隐私
比较在你的浏览器中通过内置规则引擎运行，规范不会被上传。URL 导入会直接从浏览器获取文件且不携带 Cookie，因此屏蔽跨源请求的服务器所提供的规范需要改为上传或粘贴。每份规范最大 5 MB。外部 $ref 文件会被报告但不会被获取。服务器、回调、Webhook、链接和厂商扩展不会被比较，并且这些规则描述的是可能对客户端产生的影响，而非保证：严格或宽松的服务器表现可能不同。
