About This Skill

Shipping an API update without knowing what breaks is how you lose integrators. This skill compares two versions of your OpenAPI 3.x or Swagger 2.0 spec (JSON or YAML) and reports every change that matters — from the consumer's point of view. What it detects (10 categories): 1. Removed & renamed paths, operations, parameters, response fields 2. Required-ness changes — the optional-to-required trap 3. Type & format changes, tightened constraints 4. Enum changes — including response enums that break exhaustive switches 5. Response shape — removed fields, changed status codes, content-type switches 6. Auth & security — new scopes, moved API keys, changed schemes 7. Pagination & defaults — silent behavior changes 8. Deprecations & sunsets 9. Additive changes verified as truly safe (collision check included) 10. Server & base-path changes Every finding gets a severity — BREAKING / RISKY / DEPRECATION / SAFE — cites the exact spec location (JSON path) with old and new values, and states which side breaks: request writers or response readers. You get: - A verdict and a semver recommendation (MAJOR / MINOR / PATCH) with the reason - A migration table your consumers can act on directly - A changelog draft ready to paste into release notes - A "not breaking (so no one panics)" section RISKY is a first-class category here: new response enum values, changed defaults, new error codes. A naive diff calls these safe. Your integrators' error dashboards disagree. Static analysis only — it never calls your API and never fetches URLs referenced by the spec. Not affiliated with the OpenAPI Initiative or SmartBear Software. "OpenAPI" and "Swagger" are used only to describe compatibility.