OpenAPI Diff Analyzer
Compare two OpenAPI specifications and detect breaking changes, added endpoints, and schema modifications
Enter the older version of your OpenAPI spec to use as the comparison base
Enter the newer version of your OpenAPI spec to compare against the base
What is the OpenAPI Diff Analyzer?
The OpenAPI Diff Analyzer compares two versions of an OpenAPI specification and identifies every change between them. It classifies each change as breaking or non-breaking, helping API maintainers understand the impact of their modifications before releasing a new version. All processing happens in your browser — your API specifications never leave your device.
How to Use
- Paste the older (base) OpenAPI specification in the left input
- Paste the newer OpenAPI specification in the right input
- Click "Compare Specs" or wait for automatic processing
- Review the summary showing total changes, breaking vs non-breaking
- Inspect individual endpoint diffs with color-coded severity
Example: Detecting Breaking Changes
Consider an API where you change a parameter from optional to required and change its type:
# Old spec (v1)
paths:
/users:
get:
parameters:
- name: page
in: query
required: false
schema:
type: integer
# New spec (v2) — contains breaking changes
paths:
/users:
get:
parameters:
- name: page
in: query
required: true # ← Breaking: now required
schema:
type: string # ← Breaking: type changedThe analyzer detects both changes as breaking: making a parameter required forces all existing clients to update, and changing its type breaks existing parsing logic.
What Changes Are Detected?
- Added endpoints — New paths or HTTP methods (non-breaking)
- Removed endpoints — Deleted paths or HTTP methods (breaking)
- Parameter changes — Added, removed, type changed, or required/optional toggled
- Schema modifications — Property additions, removals, type changes in request/response bodies
- Response changes — Added or removed response status codes
- Required property additions — New required fields in request bodies (breaking)
Breaking vs Non-Breaking Changes
Breaking changes can cause existing API consumers to fail. They include: removing endpoints, removing parameters, changing parameter types, making optional parameters required, removing response codes, and adding required properties to request bodies.
Non-breaking changes are backward-compatible. They include: adding new endpoints, adding optional parameters, adding response codes, and adding optional properties.
Supported Formats
Both JSON and YAML formats are supported. The tool accepts OpenAPI 3.x and Swagger 2.0 specifications. You can even compare a Swagger 2.0 spec against an OpenAPI 3.x spec — the tool normalizes both before comparing.
Performance and Large Specs
For combined inputs under 100KB, processing happens on the main thread. When both specs together exceed 100KB, processing is automatically offloaded to a Web Worker to keep the UI responsive. The tool warns at 500KB per spec and rejects inputs larger than 5MB.
Use Cases
- API versioning — Verify what changed between API releases
- Pull request review — Check OpenAPI spec changes before merging
- Client SDK updates — Know which breaking changes require client code updates
- API governance — Enforce policies about breaking changes in CI/CD pipelines
- Documentation — Generate changelogs from specification differences
Privacy and Security
All comparison happens entirely in your browser using JavaScript. Your API specifications — which may contain internal endpoints, authentication details, and business logic — never leave your device. No data is stored, logged, or transmitted.
Frequently Asked Questions
What changes does the OpenAPI Diff Analyzer detect?
The analyzer detects added and removed endpoints, added and removed HTTP methods on existing paths, parameter changes (added, removed, type changes, required/optional changes), request body modifications, response changes, and schema modifications including property additions, removals, and type changes. Each change is classified as breaking or non-breaking.
What counts as a breaking change?
Breaking changes are modifications that could cause existing API consumers to fail. These include: removing an endpoint or HTTP method, removing a parameter, changing a parameter type, making an optional parameter required, removing a response status code, changing a schema type, and adding a new required property to a request body. These changes require API consumers to update their code.
What OpenAPI formats are supported?
Both JSON and YAML formats are supported. The tool accepts OpenAPI 3.x and Swagger 2.0 specifications. Paste the full spec content (not a URL) in each input field. The tool detects the format automatically.
Is my API specification sent to any server?
No. All comparison and analysis happens entirely in your browser using JavaScript. Your API specifications — which may contain internal endpoints, authentication details, and business logic — never leave your device. No data is stored, logged, or transmitted.
How does the tool handle large specifications?
For combined inputs under 100KB, processing happens on the main thread. When both specs together exceed 100KB, processing is automatically offloaded to a Web Worker to keep the UI responsive. The tool warns at 500KB per spec and rejects inputs larger than 5MB.
Why is removing an optional parameter considered breaking?
Removing a parameter from the API spec means consumers sending that parameter will receive an unexpected behavior or error. Even if the parameter was optional, existing clients may rely on it. The safest approach is to deprecate parameters before removing them.
How is this different from the OpenAPI Viewer?
The OpenAPI Viewer displays and navigates a single specification, showing endpoints, parameters, schemas, and responses in a readable format. The OpenAPI Diff Analyzer compares two versions of a specification to identify what changed between them, which is useful during API evolution and versioning.
Can I compare Swagger 2.0 with OpenAPI 3.x?
Yes, you can compare specs of different versions. The tool normalizes paths and operations from both formats before comparing. However, some structural differences between Swagger 2.0 and OpenAPI 3.x (like the requestBody vs body parameter change) may appear as modifications in the diff results.