How do I diff two OpenAPI specs?

Paste the old spec on the left and the new spec on the right. Specway compares operations across both specs and shows added, removed, and changed operations. Removed and changed operations are flagged as potential breaking changes — clients depending on them may need to migrate.

What counts as a breaking change in OpenAPI?

Conservative answer: any removed operation, any required parameter added, any response schema with a removed required field, any change to a parameter's type, any new required body field. Less obvious: making a previously optional field required, narrowing an enum, restricting a regex pattern. Even the description being changed isn't strictly breaking — but the schema-level changes almost always are.

Why does the tool say "potential breaking change"?

Without running clients against the spec, we can't prove a change actually breaks them — clients might not use the affected operation at all. The tool flags everything that *could* break clients so you can review and decide. For a deterministic CI gate, use openapi-diff (npm package) or oasdiff for spec-level breaking-change detection.

How is this different from a textual diff?

A textual diff shows line-level changes — formatting churn, key reordering, comment edits all show up as 'differences' that don't affect clients. This semantic diff cares only about API contract changes: added/removed operations, parameter changes, body/response shape changes. Whitespace and key ordering are ignored.

Should I version-bump on every breaking change?

Yes — semver says breaking change = major version bump. In practice for APIs that means cutting a /v2 endpoint or adding a deprecation header to /v1. Communicate breaking changes 90 days before they take effect. Specway can auto-publish a CHANGELOG for your API based on the diff between published versions.

Does it diff component schemas?

The current widget compares operation-level shapes (parameters, requestBody, responses). For deep schema diffing — added/removed properties, type changes, enum changes inside components/schemas — use the openapi-diff CLI, which surfaces every leaf change. We may add a 'deep diff' toggle to this tool based on demand.

How do I diff two OpenAPI specs?

Paste the old spec on the left and the new spec on the right. Specway compares operations across both specs and shows added, removed, and changed operations. Removed and changed operations are flagged as potential breaking changes — clients depending on them may need to migrate.

What counts as a breaking change in OpenAPI?

Conservative answer: any removed operation, any required parameter added, any response schema with a removed required field, any change to a parameter's type, any new required body field. Less obvious: making a previously optional field required, narrowing an enum, restricting a regex pattern. Even the description being changed isn't strictly breaking — but the schema-level changes almost always are.

Why does the tool say "potential breaking change"?

Without running clients against the spec, we can't prove a change actually breaks them — clients might not use the affected operation at all. The tool flags everything that *could* break clients so you can review and decide. For a deterministic CI gate, use openapi-diff (npm package) or oasdiff for spec-level breaking-change detection.

How is this different from a textual diff?

A textual diff shows line-level changes — formatting churn, key reordering, comment edits all show up as 'differences' that don't affect clients. This semantic diff cares only about API contract changes: added/removed operations, parameter changes, body/response shape changes. Whitespace and key ordering are ignored.

Should I version-bump on every breaking change?

Yes — semver says breaking change = major version bump. In practice for APIs that means cutting a /v2 endpoint or adding a deprecation header to /v1. Communicate breaking changes 90 days before they take effect. Specway can auto-publish a CHANGELOG for your API based on the diff between published versions.

Does it diff component schemas?

The current widget compares operation-level shapes (parameters, requestBody, responses). For deep schema diffing — added/removed properties, type changes, enum changes inside components/schemas — use the openapi-diff CLI, which surfaces every leaf change. We may add a 'deep diff' toggle to this tool based on demand.

OpenAPI Diff (2026)

Diff two OpenAPI specs to surface added, removed, and changed operations. Flags potential breaking changes so you know when to bump the major version. Pure browser.

Old spec

New spec

+2 added−0 removed~0 changed0 potential breaking changes

DELETE /pets/{id}new operation
GET /breedsnew operation

Why API diffing matters

An API contract is a promise to your clients. Breaking that contract — removing an operation, requiring a new parameter, narrowing a response — silently breaks integrations that worked yesterday. Diffing catches these in CI so they never reach production without an explicit version bump and consumer notice.

What semver says about API versioning

Major (v1 → v2): breaking changes — any removed/renamed operation, any parameter or response that breaks existing clients.
Minor (v1.0 → v1.1): backward- compatible additions — new operations, new optional parameters, new optional response fields.
Patch (v1.0.0 → v1.0.1): bug fixes, doc improvements, no contract change.

Diffing in CI

For automated breaking-change detection on every PR, run oasdiff or openapi-diff against the spec on main. Both tools have rich breaking-change detection beyond what this widget does. Or use Specway's API breaking change detection — every spec import is automatically diffed against the previous version, with breaking changes surfaced in the changelog.

Related tools

OpenAPI Validator

Validate each version before diffing.

OpenAPI Linter

Catch documentation issues per version.

Swagger 2 → OpenAPI 3

Migrate before diffing if needed.

OpenAPI Viewer

Browse operations in either version.

Frequently asked questions

Ship API docs that stay this clean

Specway turns your OpenAPI spec into a branded developer portal — auto-synced, searchable, with built-in playground and code samples in every language. Free tier available.

Try Specway free