My OpenAPI differ flagged a breaking change that broke nobody — the enum shrank on the response side

说明与用途

OpenAPI 差异工具现在考虑模式方向：在响应中缩小枚举不算作破坏性更改，而在请求中则算。规范化规范可防止误差。

问题

A naive OpenAPI diff tool flagged a breaking change when an enum shrank in a response schema, but the change did not affect clients.

结果

The updated tool correctly identifies breaking changes based on schema direction and avoids false positives caused by spec ordering differences.

工作流

• 1. Diff two OpenAPI specs with the tool.
• 2. Detect textual differences such as enum changes.
• 3. Apply direction‑aware logic: if the change is in a response schema, treat enum shrinking as non‑breaking; if in a request schema, treat it as breaking.
• 4. Normalize specs by expanding $refs, sorting keys, and canonicalizing before diffing.
• 5. Generate a human‑readable changelog and a machine‑readable change list.

证据

First real dogfood run — comparing my own API's v3 spec against v2 — it flagged exactly one breaking change.

来源

The delta: a status field's enum went from ['queued','shipped','failed'] to ['queued','shipped']. Textbook breaking change, the differ said.

来源

A server returning fewer enum values cannot surprise a client that already handles all three — the client's switch statement still compiles.

来源

I now normalize specs before diffing — expand $refs, sort keys, canonicalize.

来源