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.

Источник