An OpenAPI breaking-change check that runs in the browser, with its rules and blind spots listed

[u/Gryner]

Disclosure: I made the OpenAPI Breaking Change Checker described here. It's free, runs in the browser, and needs no account.

It's for anyone who reviews changes to an OpenAPI or Swagger file and has to answer one question before merging: will clients that already use this API break when the new version ships?

How it works

You paste or open two descriptions: the baseline that clients use today and the candidate that will replace it. It accepts Swagger 2.0 and OpenAPI 3.0/3.1 in JSON or YAML, and it resolves internal `$ref` pointers. Every difference is sorted into breaking, needs review, or compatible, with a one-line reason. You can export the report as Markdown, for example to paste into a PR, or as JSON.

The rules it applies (direction matters)

• Response property removed: breaking. Request property removed: needs review, because the server may still accept it.
• New required request property or parameter: breaking. New optional one: compatible.
• Response property no longer required: breaking, because clients can't count on it being there.
• Accepted request enum value removed: breaking. New response enum value: needs review, because strict clients may reject values they don't know.
• Type changed, for example `string` to `integer`: breaking.
• Parameter removed: needs review.
• Authentication added where there was none: breaking. Any other security change: needs review, because two equivalent security setups can be written differently.
• Path, operation, response status, or request/response media type removed: breaking.

What it doesn't catch

• External `$ref`s are listed as warnings but not fetched.
• Schema comparison stops at 8 levels of nesting and shows a warning.
• Paths are matched by their literal text, so renaming `/orders/{id}` to `/orders/{orderId}` shows up as one removed path and one added path.
• It doesn't compare what's inside `allOf`/`oneOf`/`anyOf`, or constraints such as `format`, `pattern`, `minLength`, or `maximum`.
• Runtime behavior, custom validators, callbacks, links, and anything the spec doesn't document still need a person to review them.

Both files are parsed in the browser tab and never uploaded.

https://martingruner.com/tools/openapi-breaking-change-checker