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.複製破壞性變更用於 Pull Request，或下載 Markdown 或 JSON 報告用於 CI。
變更如何分類
請求與回應是以相反的方向來判斷。在請求端（用戶端傳送的內容），任何縮窄可接受範圍的變更都屬於破壞性變更：新增必填參數或屬性、移除列舉值、變更類型或格式、調低最大值或調高最小值、新增正規表示式模式，或移除內容類型。在回應端（用戶端接收的內容），任何移除或放寬用戶端所讀取內容的變更都屬於破壞性變更或警告：移除屬性或成功狀態碼、變更類型、新增列舉值，或必填屬性變為選填。移除端點、新增驗證、變更安全性機制以及新增 OAuth 範圍都屬於破壞性變更。對描述、摘要、標題與範例的修改屬於文件變更，除非你將其開啟，否則預設隱藏。
限制與隱私
比較是在你的瀏覽器中透過內建規則引擎執行，規格不會被上傳。URL 匯入會直接從瀏覽器擷取檔案且不帶 Cookie，因此封鎖跨來源請求的伺服器所提供的規格需要改為上傳或貼上。每份規格最大 5 MB。外部 $ref 檔案會被回報但不會被擷取。伺服器、回呼、Webhook、連結與廠商擴充不會被比較，而且這些規則描述的是可能對用戶端造成的影響，而非保證：嚴格或寬鬆的伺服器行為可能不同。
