OpenAPI Diff Tool — Detect Every Change, Automatically
Compare any two OpenAPI specifications and get a complete, categorized report of every breaking change, deprecation, and schema modification — in seconds.
What the Diff Engine Detects
CodeRifts goes far beyond a simple text diff. It understands the semantics of your OpenAPI specification and categorizes every change by type and severity.
10 Breaking Change Types
- ✕ Endpoint removed
- ✕ Required request field added
- ✕ Response field removed
- ✕ Response type changed
- ✕ Enum value removed
- ✕ Authentication scheme changed
- ✕ Request body format changed
- ✕ Path parameter renamed
- ✕ Required header added
- ✕ Default value changed
Non-Breaking Changes
- ✓ New endpoint added
- ✓ Optional request field added
- ✓ New response field added
- ✓ Description updated
- ✓ Enum value added
- ✓ New optional header
CodeRifts also detects deprecations, security changes, and documentation drift — giving you a complete picture of what changed and why it matters.
Why Automated OpenAPI Diffing Matters
Manually comparing two versions of an OpenAPI specification is not only tedious but also highly error-prone. As APIs evolve, their specifications can grow to thousands of lines, with complex interdependencies managed through $ref components. A simple text-based diff, like the one you might see in a Git commit, is insufficient because it fails to understand the semantic meaning of the OpenAPI structure.
Automated tooling is essential for managing this complexity. A purpose-built OpenAPI diff tool doesn't just compare text; it parses the specification, resolves all references, and understands the hierarchical structure of the API contract. For example, changing a property from optional to required within a referenced schema is a significant breaking change, but it might appear as a minor, one-word alteration in a text file.Without an automated, semantically-aware diff, teams risk shipping breaking changes unknowingly.
How CodeRifts Performs the Diff
CodeRifts provides a sophisticated diff engine that goes beyond simple comparison to deliver a comprehensive and actionable report. At its core, the process involves parsing both the old and new OpenAPI specifications, whether they are in version 2.0 (Swagger), 3.0, or 3.1. The engine fully resolves all internal and external $ref pointers, creating a complete, canonical representation of each API version.
Once the specs are fully resolved, CodeRifts performs a semantic comparison of the two structures. It categorizes every detected change—from a removed endpoint to a modified response schema—according to its severity: breaking, non-breaking, or deprecation. Each change is then assigned a risk score based on factors like the type of change and its potential impact on consumers. The final output is a rich, interactive report that helps teams make informed decisions.
Use Cases
CI/CD Pipelines
By incorporating CodeRifts into your Continuous Integration and Continuous Deployment (CI/CD) pipeline, you can automatically fail builds that introduce high-risk or unauthorized breaking changes. You can use our CLI or REST API to add a diff check as a required step in your deployment workflow.
Pre-Merge Checks
With the CodeRifts GitHub App, every pull request that modifies an OpenAPI file gets an automatic check. A detailed comment is posted directly on the PR, showing a summary of the changes and a link to the full diff report. This enables developers and reviewers to understand the impact of their changes before they are merged.
API Versioning Strategy
Automated diffing is fundamental to a sound API versioning strategy. By understanding the nature of every change, you can make deliberate decisions about when to release a new minor version (for non-breaking, backward-compatible changes) versus a new major version (for breaking changes).
Migration from Swagger to OpenAPI 3.x
Upgrading a legacy Swagger 2.0 specification to OpenAPI 3.0 or 3.1 can be a complex process with many potential pitfalls. Using the CodeRifts diff tool, you can compare your old Swagger file with the newly converted OpenAPI 3.x file to verify that the API's contract has not been unintentionally altered during the migration.
Three Ways to Diff
In-Browser
Upload two specs to app.coderifts.com/try and get a full report instantly. No signup required.
On Every PR
Install the GitHub App and CodeRifts automatically diffs your OpenAPI specs on every pull request. Zero config.
More Than a Diff — A Full Governance Report
Every diff includes risk scoring, policy enforcement, security analysis, and an auto-generated changelog. It's not just what changed — it's whether you should ship it.
Risk Score
Every change gets a 0–100 risk score based on severity, blast radius, and affected consumers.
Policy Engine
Enforce naming conventions, deprecation timelines, and versioning rules automatically.
Security Analysis
Detect authentication downgrades, exposed sensitive fields, and OWASP API risks.
Auto-Changelog
Get a human-readable changelog generated from the diff — ready for release notes.
Frequently Asked Questions
What is an OpenAPI diff?
An OpenAPI diff (or differential) is the result of comparing two versions of an OpenAPI specification to identify all the changes between them. Unlike a simple text diff, a proper OpenAPI diff tool understands the structure and semantics of the specification. It can pinpoint specific changes like a removed endpoint, a modified data type, or a new required parameter, and classify them as breaking or non-breaking.
How do I compare two OpenAPI specs?
You can compare two OpenAPI specs using a specialized tool like CodeRifts. You can use our free in-browser tool by simply uploading your two specification files. For a more automated workflow, you can integrate our GitHub App to get a comparison on every pull request, or use our CLI or REST API to run a comparison in your own scripts or CI/CD pipelines.
What counts as a breaking change?
A breaking change is any modification to an API contract that can cause existing client applications to fail. Common examples include removing an endpoint, adding a new required request parameter, removing a field from a response, or changing the data type of a field. CodeRifts maintains a comprehensive list of over 10 common breaking change types that it detects automatically.
Does CodeRifts support OpenAPI 3.1?
Yes, CodeRifts has full support for OpenAPI 3.1, as well as OpenAPI 3.0 and OpenAPI 2.0 (formerly known as Swagger). Our diff engine is designed to handle the nuances and features of each version, including the latest additions in 3.1 like webhooks and improved JSON Schema compatibility.
Can I use this in CI/CD?
Absolutely. Integrating API diffing into your CI/CD pipeline is a best practice for preventing breaking changes from reaching production. CodeRifts provides both a CLI tool and a REST API that you can easily incorporate into your existing workflows, whether you use Jenkins, GitLab CI, CircleCI, or any other automation server. You can configure your pipeline to fail a build if a high-risk breaking change is detected.
Try the diff engine now — free.
Upload two OpenAPI specs and see the full report in seconds. No signup, no credit card.
See all 61+ features or compare pricing plans.