What this tool does
Paste, upload, or load an example for two versions of an OpenAPI/Swagger document and get back a list of what changed between them — endpoints, parameters, request bodies, and response schemas — each one flagged as breaking or non-breaking for existing API consumers. That classification is the part a generic text or JSON diff can't give you: it tells you whether it's safe to ship.
How breaking is decided
The rule of thumb throughout: a change is breaking if a client written against the old spec would stop working against the new one.
- Breaking: an endpoint removed, a new required parameter or request field, an optional parameter or field becoming required, a parameter or field's type changing, or a field disappearing from a response that a client may have been reading.
- Non-breaking: a new endpoint, a new optional parameter, a new optional response field, a required parameter relaxed to optional, or a parameter/field being removed from a request (existing requests just stop sending something the server no longer needs).
Request-side and response-side changes are judged in opposite directions on purpose. A newly required request field breaks old clients that don't send it. A newly required response field doesn't break anything — old clients simply ignore fields they don't recognize. The direction that matters is always "does the client that hasn't changed still work."
How $ref is handled
Both documents resolve their own $ref references independently before comparing, so a schema shared across many endpoints — like a Pet object reused in five different responses — is compared once per endpoint that uses it. If that shared schema loses a field, every affected endpoint shows up individually, which is exactly what you want to know before shipping: not just that a type changed, but everywhere it's going to matter.
FAQ
Does this replace a full spec-conformance check?
No — this tool assumes both documents are individually valid and focuses purely on what changed between them. To check a single document for spec violations first, use the OpenAPI Validator.
I just want to browse one version
The OpenAPI Viewer renders a single document as a readable, searchable list of endpoints.
Are my specs uploaded anywhere?
No — the comparison happens entirely in your browser. Nothing is sent to a server.