Compare specs

一个独立页面(侧边栏中链接为“Compare specs”),按 URL 拉取两份 OpenAPI 文档,并报告它们之间的差异:新增、删除和变更的端点,每一处都会被标记为破坏性或提示性。

用法

点击侧边栏中的 Compare specs,为基准(旧)spec 和新 spec 各粘贴一个 URL(新 spec 输入框会预填当前已加载的那份),然后点击 Compare。两份文档都会经过主查看器所用的同一套 normalizeDocument() 流程,所以不存在另一套需要另行信任的解析逻辑。

什么算破坏性变更

ChangeSeverity
端点被删除破坏性
新增必填参数破坏性
可选参数变成必填破坏性
请求体变成必填破坏性
某个 2xx 响应被删除破坏性
端点被新增提示性
参数被删除提示性
某个非 2xx 响应被删除提示性
记录了新的响应状态码提示性

范围

这个功能刻意做得比较浅:它比较的是端点是否存在、参数是否存在/是否必填、请求体是否必填,以及响应状态码。它不会逐字段比对 schema 结构(比如某个属性悄悄从 string 变成 number,目前还捕捉不到)。