規格差異

把兩份 .zwaggen.json 檔案並排比較，看看變了什麼、以及是不是破壞性。為 PR 審查而設計。

如何比較

• 點擊頂列的 比較（Compare）。
• 選擇「before」規格檔案（例如 main 上的版本）。

差異面板會打開。應用程式中目前的規格被視為「after」；你選的檔案是「before」。

什麼算是變更

端點

以 (method, path) 比對。存在性變更：

• 只在「before」中 → 移除 → 破壞性。
• 只在「after」中 → 新增 → 非破壞性。
• 兩邊都在 → 變更，依細節再分類。

細節層級的破壞性（不完全列舉；完整清單在 repo 的 docs/specs/done/2026-04-18-spec-diff.md）：

• 新的必填參數，或選填參數改為必填 → 破壞性。
• 請求內容新增，或其型別被收窄 → 破壞性。
• 既有狀態上的回應型別變了 → 破壞性。
• 新的選填參數、描述變更、tag 變更、新增回應狀態 → 非破壞性。

型別

以名稱比對。

• 型別被移除 且 仍被任何端點參照 → 破壞性。未被參照的移除 → 非破壞性。
• 型別新增 → 非破壞性。
• Object：欄位移除、欄位以必填身分新增、欄位從選填 → 必填、欄位型別變更 → 破壞性。反向則為非破壞性。
• String：enum 收縮、pattern 新增或收緊、minLength 上調 / maxLength 下調 → 破壞性。
• Number：min 上調、max 下調、enum 收縮 → 破壞性。

你會看到什麼

• 標題：「N 個破壞性、M 個非破壞性 變更」。
• 兩個區塊：破壞性（紅色 chip）與 非破壞性（石板色 chip）。
• 每一列：[kind] chip + 位置（例如 POST /users）+ 一行摘要。

它不會告訴你的

• 不是完整結構化 diff — 空白與順序會被忽略。
• 沒有遷移指引。它只分類，不建議修法。
• 一次只能比較兩份規格。
• 沒有 git 整合 — 你要自己選「before」檔案。

典型用途

• PR 審查。 核准規格變更前，將 PR 分支的 .zwaggen.json 與 main 的相比。任何進到紅色那堆的都值得在 PR 描述裡附上破壞性變更說明。
• 發版前把關。 將即將發佈的規格與上一次發佈的相比；若出現破壞性項目，請把 API 版號升大版（major）。