OpenAPI Diff

Paste two versions of an OpenAPI or Swagger spec and get a clear changelog of what differs between them. Every difference is sorted into breaking (will break existing clients), non-breaking (safe to ship), or informational — covering removed and added operations, parameter changes, newly required fields, request-body and response changes, and schema edits. JSON or YAML, compared entirely in your browser.

How to use the OpenAPI Diff

Paste the previous version of your API spec on the left and the new one on the right — both JSON and YAML are accepted, and the two can be in different formats. The diff runs as you type and groups every change into three buckets: breaking changes that can break existing clients (a removed endpoint, a new required parameter, a dropped response code), non-breaking additions that are safe to deploy (a new optional parameter, an extra endpoint), and informational notes (a deprecation, a new schema). Counts appear at the top so you can tell at a glance whether a release is safe.

Use the breaking list as a release gate: if it's empty, the new version is backward-compatible at the contract level. The comparison looks at paths and operations, parameters (path, query, header), request-body requirements, response status codes, and component schemas including required properties and property types. It compares the contract shape, not prose — a reworded description won't be flagged, but a property whose type changed from string to integer will.

Breaking vs. non-breaking API changes

An API contract is a promise to its clients: these endpoints exist, they take these parameters, and they return these shapes. A breaking change is any edit that violates that promise in a way that can make a previously working client fail — removing an endpoint, requiring a parameter that used to be optional, deleting a field a client reads, or changing a field's type. A non-breaking change adds capability without invalidating existing calls: a new endpoint, a new optional parameter, an additional response code, or a new field clients can ignore. Telling the two apart by eye across a large spec is slow and error-prone, which is exactly where automated diffing helps.

The classification follows the direction of compatibility. Removing something the client depends on is breaking, because the client still expects it. Adding something is usually safe, because old clients simply won't use it. Tightening a requirement — making an optional parameter required, marking a request body mandatory, adding a required property to a schema — is breaking, because requests that were valid before are now rejected. Loosening a requirement is non-breaking. A few changes are neither strictly safe nor strictly breaking but worth knowing about, like marking an operation deprecated; those land in the informational bucket so they don't get lost.

This kind of diff is most valuable in CI and code review. Running it on every pull request that touches the spec turns "did we break the API?" from a judgement call into a checklist: the breaking list is your gate. It complements, rather than replaces, semantic versioning — a non-empty breaking list means the change deserves a major version bump and a migration note for consumers. Because the whole comparison happens in your browser, you can paste internal or unreleased specs without sending them anywhere.

Common use cases

• Release gating. Confirm a new API version is backward-compatible before shipping it.
• Code review. See exactly which operations, parameters, or schemas a spec change touches.
• Versioning decisions. Use the breaking-change list to decide between a major and minor bump.
• Migration notes. Generate the starting point for a changelog or upgrade guide for consumers.