Compare specs
一个独立页面(侧边栏中链接为“Compare specs”),按 URL 拉取两份 OpenAPI 文档,并报告它们之间的差异:新增、删除和变更的端点,每一处都会被标记为破坏性或提示性。
用法
点击侧边栏中的 Compare specs,为基准(旧)spec 和新 spec 各粘贴一个 URL(新 spec 输入框会预填当前已加载的那份),然后点击 Compare。两份文档都会经过主查看器所用的同一套 normalizeDocument() 流程,所以不存在另一套需要另行信任的解析逻辑。
什么算破坏性变更
| Change | Severity |
|---|---|
| 端点被删除 | 破坏性 |
| 新增必填参数 | 破坏性 |
| 可选参数变成必填 | 破坏性 |
| 请求体变成必填 | 破坏性 |
| 某个 2xx 响应被删除 | 破坏性 |
| 端点被新增 | 提示性 |
| 参数被删除 | 提示性 |
| 某个非 2xx 响应被删除 | 提示性 |
| 记录了新的响应状态码 | 提示性 |
范围
这个功能刻意做得比较浅:它比较的是端点是否存在、参数是否存在/是否必填、请求体是否必填,以及响应状态码。它不会逐字段比对 schema 结构(比如某个属性悄悄从 string 变成 number,目前还捕捉不到)。