OpenAPI Diff

Compare two versions of an OpenAPI document and see which operations, parameters, and schema properties were added, removed, or changed, with breaking changes flagged first. It is free, needs no account, and your documents never leave your browser.

The sample compares version 1.0.0 and 2.0.0 of a small Galaxy Planets API. Version 2 removes the delete operation, adds a required galaxy query parameter, changes planet IDs from integers to strings, and drops the radius field, so it reports seven breaking changes. That is a realistic day: most of them come from one schema edit.

How the OpenAPI diff works

Both documents are parsed as JSON or YAML. Swagger 2.0 input is first upgraded to OpenAPI 3.1 with upgrade() from @scalar/openapi-parser, so you can compare a Swagger 2.0 document with its OpenAPI 3 successor. Local $ref values are inlined, so a change to a shared schema shows up in every operation that uses it.

Operations are matched by method and path. Path parameter names do not matter for matching: /planets/{planetId} and /planets/{id} are the same route to a client, and the rename is reported as a note. For each matched operation the tool compares parameters, the request body, and every response, walking into schema properties and array items.

Direction matters when deciding what breaks. A request schema may accept more than before, but not less. A response schema may promise more than before, but not less. So adding null to a request field's type is fine, and adding it to a response field's type is breaking, because clients that assumed a string now get null.

What counts as breaking

Warnings are changes that break some clients: a strict client that validates enums rejects a value it has never seen. Copy report gives you a plain-text list to paste into a pull request or changelog.

Limits

• Structure, not behavior. The diff compares what the documents say. A change in validation rules, rate limits, or error behavior that the documents do not describe is invisible to it.
• A focused rule set. It covers operations, parameters, request bodies, responses, and schema properties, types, required lists, and enums. Security requirements, headers on responses, examples, and descriptions are not compared.
• JSON bodies first. When an operation has several media types, the JSON one is compared.
• Composition keywords. Schemas built with oneOf, anyOf, and allOf are compared on their top-level type and properties only, so review those by hand.
• Local references only. External $ref files are not fetched. Bundle multi-file documents first.

When to run a diff

Run it before you release, on the document your server will publish, against the one clients are using today. If the report has breaking changes, you have three options: undo them, ship them in a new major version, or give clients a deprecation period. The API documentation best practices guide covers changelogs, and generated SDKs make the new version easy to adopt.

Built on @scalar/openapi-parser

The page loads @scalar/openapi-parser and yaml from jsDelivr, pinned to exact versions. The comparison is a short module you can read in the scalar/scalar repository under documentation/assets/free-tools. Validate both documents with the OpenAPI validator first, because a diff of an invalid document is hard to trust.

Keep docs in sync with every version

Scalar can republish your API reference automatically whenever your OpenAPI document changes, so the docs your users read always match the version you shipped.

Frequently asked questions

Related

• Learn: API documentation best practices · What is OpenAPI?
• Docs: OpenAPI validator · OpenAPI converter · Scalar CLI commands
• Product: Scalar Registry — version your OpenAPI documents in one place, with docs that follow each release