Why it matters
Most API breakages aren't deliberate. Someone tightens a maximum, adds a required field, drops a property nobody seemed to use or adds a new enum value, and a mobile app that can't be updated overnight starts failing. Whether a change breaks clients depends on which way the data flows: a new required field is fine in a response but breaks every client in a request; a new enum value is harmless in a request but can crash a client that switches on it in a response.
This tool reads both specs, matches endpoints by method and path (so renaming {id} to {productId} isn't a removal), and walks every parameter, request body and response schema, following $refs, with those direction rules. Each change is marked breaking, to check or safe, with the reason. It also lints the new spec with the same rules as the OpenAPI viewer, validates its examples against their schemas, checks the version number says what the changes say, and writes a changelog you can paste into a pull request. Nothing is uploaded.
How it works
- InputThe old and new OpenAPI specs
- In your browserRequests and responses compared in the right direction
- OutputBreaking changes, lint and a changelog
Where it fits in a designer's workflow
- Plan
- Design
- Build
- Test
- Launch
By the numbers
Show the numbers as a table
| Severity | Changes |
|---|---|
| Breaking | 9 |
| To check | 4 |
| Non-breaking | 4 |
How to use it
- Paste the spec as it is now (old) and the version you're about to ship (new).
- Read the breaking changes first, then the ones to check.
- Fix the lint errors in the new spec, starting with examples that don't match.
- Copy or download the Markdown changelog for your release notes or pull request.
FAQ
What counts as a breaking change?
Anything that can make a request that worked before fail, or a response a client relied on look different: removed endpoints, new required parameters or fields, tighter limits on what clients send, removed enum values in requests, and removed or no-longer-guaranteed fields or changed types in responses.
Why is a new enum value only a warning?
In a response it's a change clients may not handle: code that switches on status and has no default branch will fail on refunded. Many APIs document that new values can appear, so it's flagged to check rather than as breaking.
Why isn't renaming a path parameter breaking?
Clients only see the URL, not the parameter's name in the spec, so /products/{id} and /products/{productId} are the same endpoint. Generated client code can change, so check your SDKs.
Does it follow $refs?
Yes, local references (#/components/... and #/definitions/...), including recursive schemas. External files aren't fetched; bundle the spec first.
How does this compare with oasdiff or openapi-diff?
It covers the common rules those command-line tools check, without installing anything, and explains each one in plain English. For CI, a command-line tool is still the right choice.
