How to Compare OpenAPI Specifications
Follow these quick steps to audit API changes between two OpenAPI definitions:
- Paste or upload your Old Spec: Place your current production OpenAPI document in the left editor.
- Paste or upload your New Spec: Place the proposed OpenAPI contract revision in the right editor.
- Inspect Changes: Switch to the Changes & Report view to see every modification organized by severity.
- Review Breaking Risks: Click any change item to view the exact JSON path, side-by-side snippet diff, and remediation advice.
- Export Changelog: Download a GitHub-ready Markdown changelog, CSV spreadsheet, or pull request summary comment.
Before & After Example: Breaking Changes
Consider an endpoint where a parameter becomes mandatory, and an enum option is removed:
# Base Spec (v1.0.0)
paths:
/orders:
post:
parameters:
- name: coupon_code
in: query
required: false
requestBody:
content:
application/json:
schema:
properties:
status:
enum: [pending, paid, cancelled]
# Updated Spec (v1.1.0) - Contains 2 Breaking Changes
paths:
/orders:
post:
parameters:
- name: coupon_code
in: query
required: true # BREAKING: Parameter became required
requestBody:
content:
application/json:
schema:
properties:
status:
enum: [pending, paid] # BREAKING: 'cancelled' variant removed
Why Automated OpenAPI Diffing Matters
In microservice and distributed architectures, accidental breaking changes to REST API specifications break mobile applications, third-party integrations, and automated partner workflows. Detecting breaking changes during code review or CI testing prevents downtime, customer escalations, and uncoordinated client rollouts.
Frequently Asked Questions
What is considered a breaking API change?
A breaking API change modifies an existing interface in a way that causes currently deployed clients or SDKs to fail without code revisions. Examples include deleting an endpoint or method, making an optional request parameter mandatory, altering property data types, removing enum options, or removing an HTTP response status code.
Does this tool support Swagger 2.0?
The parser is built specifically for modern OpenAPI 3.0 and 3.1 specifications. Basic endpoints and methods from Swagger 2.0 documents will parse, but modern OpenAPI 3 schema components, request bodies, and media types provide the highest fidelity diffing.
Does it resolve remote $ref pointers?
To guarantee complete privacy, offline capability, and zero network leaks, external HTTP $ref pointers are not fetched across the network. Local component pointers (such as #/components/schemas/...) are resolved in memory with circular dependency cycle protection.
Is my API specification uploaded anywhere?
No. All YAML and JSON parsing, schema evaluation, and diff generation execute 100% inside your browser's local memory. No data is ever sent to any remote server or third party.