OpenAPI Diff Viewer

Compare two OpenAPI / Swagger specs (JSON or YAML) and instantly see breaking, non-breaking, and informational changes — endpoints, parameters, request bodies, responses, and schemas.

Left Spec (Old / Base)
Right Spec (New / Updated)

What It Detects

  • Added / removed endpoints and operations
  • Parameter changes (added, removed, required, type)
  • Request body changes & content types
  • Response status code & content changes
  • Component schema property changes
  • Deprecation, summary, tag, and version updates

Severity Levels

  • Breaking — clients will break (removed endpoint, required param added, type changed)
  • Non-breaking — safe additions (new endpoint, optional param, new response code)
  • Info — metadata only (description, summary, tags)

Privacy & Speed

  • 100% client-side — nothing is uploaded
  • Safe for private and internal API specs
  • No sign-up, no rate limits, no API keys
  • Instant — runs entirely in your browser
  • Free and open to use

About the OpenAPI Diff Viewer

The OpenAPI Diff Viewer compares two OpenAPI (or legacy Swagger) specifications and produces a categorized changelog. It accepts both JSON and YAML, automatically detects the format, and walks the spec to find changes in paths, operations, parameters, request bodies, responses, and component schemas.

Every change is classified by severity. Breaking changes are the ones that will cause existing clients to fail — removed endpoints, parameters that became required, types that changed, response codes that disappeared. Non-breaking changes are additive and safe — new endpoints, new optional parameters, additional response codes. Informational changes are metadata-only — descriptions, tags, summary text. Everything runs in your browser, so private and internal API specs are safe to compare here.

How to Use the OpenAPI Diff Viewer

  1. Paste the older or base spec into the Left Spec box, or click Upload to load a .yaml, .yml, or .json file.
  2. Paste the newer spec into the Right Spec box, or upload a file the same way.
  3. Click Compare — the tool parses both specs and runs the diff. If a spec is invalid, an error message appears under the affected box.
  4. Read the summary cards at the top — they show counts of breaking, non-breaking, and informational changes at a glance.
  5. Use the Filter chips to narrow down to only breaking changes (most useful for release notes), non-breaking (additive changes), or info (descriptive updates).
  6. Each change is grouped by the operation or schema it affects, so you can review the impact endpoint-by-endpoint.
  7. Click Copy Report to copy a plain-text summary to your clipboard — handy for changelogs, PR descriptions, release notes, or migration guides.
  8. Click Swap Sides to flip the comparison direction, or Load Sample to see the tool in action with a worked example.

Common Use Cases

  • API release notes — generate a clear list of what changed between two versions of an API.
  • Pull request reviews — paste the spec from main and from a feature branch to see exactly what an API change introduces.
  • Breaking-change detection — surface contract-breaking changes before they ship and break downstream consumers.
  • Client migration guides — produce a categorized list of changes to help client developers upgrade.
  • Backend ↔ frontend coordination — show the frontend team exactly which endpoints, parameters, or fields they need to update.
  • API governance — review specs from different teams or services for unexpected breaking changes.
  • Documentation drift — compare a published spec to the actual implementation's spec to find stale docs.
  • Versioned APIs — diff v1 vs v2 specs to plan deprecation timelines and sunset notices.

Frequently Asked Questions

Is my OpenAPI spec sent to a server?

No. The entire diff runs in your browser using JavaScript. Your specs, endpoint paths, parameter names, schema definitions, and any embedded examples never leave your device, so it's safe to use with private or internal APIs.

Which OpenAPI versions are supported?

It works with OpenAPI 3.x specs as well as legacy Swagger 2.0 specs. For Swagger 2.0, schemas under definitions are compared the same way OpenAPI 3.x compares components.schemas.

Does it accept YAML and JSON?

Yes. Paste either format into either side — the tool auto-detects whether the input starts with a JSON object/array and falls back to YAML otherwise. You can also mix formats: left as YAML, right as JSON (or vice versa).

What counts as a breaking change?

Anything that will make existing client code fail: a removed endpoint or operation, a required parameter being added, an optional parameter becoming required, a parameter type changing, a removed response code, a removed content type on a response, a request body becoming required, a removed schema, or a schema property being removed or made required.

What counts as a non-breaking change?

Additive changes that don't impact existing clients: new endpoints, new operations on an existing path, new optional parameters, new response status codes, new response content types, new optional schema properties, and operations being marked as deprecated (clients still work, but get notice).

Does it follow $ref references?

References are preserved as-is during comparison. Component schemas under components.schemas are compared independently in their own section, so changes to a referenced schema show up there even if multiple endpoints reuse it.

Can I upload large spec files?

Yes. Click the Upload link in the header of either input box and pick a .json, .yaml, or .yml file. Since processing is local, performance scales with your machine — typical specs of a few hundred endpoints diff in well under a second.

Why are some changes labeled "Info" instead of breaking or non-breaking?

Pure documentation updates — operation summaries, descriptions, tags, and the API version string in info.version — don't change the contract, so they're surfaced as informational. Filter by Info when writing release notes that mention documentation polish.

Can I use this for commercial work?

Yes. The tool is free for any use — commercial, internal, educational, or personal. Since nothing is transmitted off your device, there are no data-privacy concerns for proprietary API specs.