OpenAPI Diff Checker
Compare two OpenAPI or Swagger specifications online and detect breaking changes instantly. Compare endpoints, parameters, request bodies, response schemas, and security requirements in your browser.
3 breaking change(s) detected. Existing API clients may fail.
Request body made required on POST /users
Property type changed: User.id
Required property added: User.email
How to Use
1. What is an OpenAPI Diff & Semantic Comparison?
An OpenAPI Diff Checker & Breaking Change Detector is a specialized developer tool built for modern API governance, continuous integration (CI/CD) pipelines, and API contract evolution. While classic text diff utilities (like Git diff or generic JSON diffs) compare characters, line formatting, and property ordering, an OpenAPI Diff engine interprets the semantic contract of your RESTful API.
APIs serve as the foundational interface between backend microservices, web apps, native mobile clients, and third-party partner integrations. Any unintentional contract regression—such as removing an HTTP method, adding a mandatory request parameter without a default, or altering a response payload property from an integer to a string—can trigger runtime outages, deserialization crashes, and failed SDK builds across hundreds of client applications.
Analyzes Swagger 2.0, OpenAPI 3.0, 3.1, and 3.2 specifications in JSON and YAML, normalizing cross-version models effortlessly.
All diff calculations and schema comparisons run locally in your web browser. Zero API keys, schemas, or server endpoints are ever uploaded.
Instant generation of GitHub-ready release changelogs, SemVer version bump recommendations, and step-by-step developer migration guides.
2. How to Compare OpenAPI Specifications
Follow these 6 steps to compare two OpenAPI or Swagger specifications online:
- Load Base (Old) Specification: Paste your current production OpenAPI specification into the left editor, upload a
.yaml/.jsonfile, or choose a pre-configured sample from the Load Example dropdown. - Load Target (New) Specification: Paste your proposed or revised API specification into the right editor.
- Execute Semantic Diff: Click [Compare Specs] (or press Ctrl + Enter / Cmd + Enter).
- Review Compatibility Summary: Inspect the overall compatibility status (✓ No Breaking Changes, ⚠ Breaking Changes Detected, or ⚠ Potentially Breaking) and the 0–100 compatibility score.
- Inspect Categorized Changes: Browse the filterable report tabs (Breaking, Potential, Non-Breaking, Info) or explore dedicated Endpoints, Schemas, and Parameters explorers.
- Generate Release Artifacts: Click [Generate Changelog] or [Generate Migration Guide] to export release notes and SDK upgrade instructions in Markdown or JSON format.
3. Breaking vs. Non-Breaking API Changes Explained
In API design, backward compatibility dictates whether an existing client application compiled against specification Version A can continue communicating successfully with a backend implementing specification Version B without modifying client code.
- Removing an existing endpoint path (e.g.
DELETE /users/{id}) - Removing an HTTP operation from a path
- Adding a new required request parameter or header
- Changing an optional parameter to required
- Narrowing a parameter or schema property data type
- Removing a response status code (e.g. HTTP 200 or 204)
- Removing a property from a 2xx response payload
- Deleting accepted enum values from request fields
- Adding authentication requirements to a public endpoint
- Adding a completely new endpoint path or method
- Adding an optional request query parameter or header
- Relaxing a required parameter to optional
- Adding an optional property to a request body
- Adding a new field to a response body (assuming lenient clients)
- Adding support for new response status codes (e.g. 202 Accepted)
- Adding new allowed enum values to responses
- Adding new server URLs, tags, descriptions, or examples
4. Endpoint & HTTP Operation Comparison Rules
The comparison engine tracks every URI path template and associated HTTP methods (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD, QUERY).
| Contract Change | Severity | Client Impact & Technical Reason |
|---|---|---|
| Path / Method Removed | BREAKING | Existing clients calling this operation will receive HTTP 404 or 405 errors. |
| New Path / Method Added | NON-BREAKING | Expands API capabilities. Existing clients remain 100% functional. |
| operationId Renamed | POTENTIAL | Generated SDK client libraries change method signatures (e.g. client.getUser() → client.fetchUser()). |
| deprecated: true Added | INFO | Signals upcoming retirement. Operation remains callable until decommissioned. |
5. Parameter & Query String Comparison Rules
Parameters in path, query, header, and cookie locations are evaluated for requirement constraints, data types, formats, and default values.
| Parameter Mutation | Classification | Why It Matters |
|---|---|---|
| New Required Parameter | BREAKING | Legacy clients omitting the parameter will trigger HTTP 400 Bad Request validation errors. |
| Optional → Required | BREAKING | Clients that previously omitted the parameter are immediately broken. |
| Parameter Type Changed | BREAKING | Changing parameter schema from integer to UUID or string causes type coercion failures. |
| New Optional Parameter | NON-BREAKING | Safe addition. Server supplies default behavior when omitted. |
6. Request Body & Media Type Comparison Rules
Request body comparison checks both top-level requirement flags (required: true/false) and media type maps under content (e.g. application/json, multipart/form-data).
- Request Body Made Required: Classified as BREAKING. Clients sending empty POST/PUT bodies will be rejected.
- Media Type Removed: Removing
application/xmlorapplication/x-www-form-urlencodedis BREAKING for clients sending that Content-Type header. - New Media Type Added: Adding support for
application/vnd.api+jsonis NON-BREAKING.
7. Response Status Code & Schema Comparison Rules
Responses dictate what clients can expect back from the server under various operating conditions.
Critical Response Diff Rules:
- Removing Status Codes: Deleting
204 No Contentor200 OKfrom the responses block is BREAKING. - Removing Response Fields: Deleting properties from response schemas (e.g. removing
User.email) is BREAKING for client deserializers. - Adding Response Status Codes: Adding
202 Acceptedis generally NON-BREAKING for standard REST clients.
8. Data Model & JSON Schema Comparison Rules
Components and Schema Definitions under components.schemas or Swagger definitions represent your domain data models.
The diff engine compares property definitions, requirement arrays, property data types, enum options, and validation constraints (minimum, maximum, minLength, maxLength).
9. Security Schemes & Authentication Requirement Changes
Authentication and authorization changes have high blast radiuses for automated API consumers.
- Adding Security to Public Operation: Adding
security: [BearerAuth: []]to an unauthenticated endpoint is a BREAKING change (unauthenticated requests immediately return HTTP 401). - Deleting Security Schemes: Deleting an API Key or OAuth2 security scheme from
components.securitySchemesis BREAKING.
10. Semantic Versioning (SemVer) & Version Recommendations
ToolMono adheres to the official Semantic Versioning (SemVer 2.0.0) specification when analyzing API versions:
11. Generating Automated API Release Changelogs
Writing manual API release notes is tedious and error-prone. ToolMono automatically parses the diff report and compiles a clean, formatted Markdown changelog structured into 🚨 Breaking Changes, ⚠️ Potentially Breaking, ✨ New Endpoints, and 📝 Documentation Updates.
12. Creating Step-by-Step Developer Migration Guides
Whenever breaking changes are detected, ToolMono synthesizes an actionable, step-by-step developer migration guide with concrete before-and-after payload diffs and recommended client update actions.
13. OpenAPI Diff vs. Generic JSON/Git Text Diff
Generic text diff tools compare files line-by-line. A reordered JSON object or an edited YAML comment produces false positive line diffs. In contrast, an OpenAPI Diff engine understands that JSON key order is semantically irrelevant, focusing solely on the actual REST API contract.
14. How to Review API Contract Changes Before Deployment
Integrate OpenAPI contract review into your team's pull request workflow:
- Generate the new OpenAPI specification during your CI build.
- Compare the generated artifact against the current production branch spec.
- Block merges if breaking changes are introduced on minor or patch version branches.
15. Privacy & 100% Client-Side In-Memory Security
ToolMono processes all YAML and JSON specifications entirely inside your web browser via client-side JavaScript. No specification contents, server URLs, bearer tokens, or API credentials are ever sent to remote servers or analytics platforms.
16. Authoritative References & Standards
Consult official standards from the OpenAPI Initiative (OAI) and the Internet Engineering Task Force (IETF):
OpenAPI Specification v3.1.0 Official Standard
Official specification standard published by the OpenAPI Initiative (OAI) under the Linux Foundation.
OpenAPI Specification v3.0.3 Official Standard
Official specification standard for OpenAPI 3.0 REST API descriptors.
Semantic Versioning 2.0.0 Specification
Standard specification for software versioning and backward compatibility rules.
Swagger 2.0 Specification Reference
Classic Swagger 2.0 API specification format reference.
JSON Schema Specification (Draft 2020-12)
Official JSON Schema standard utilized by OpenAPI 3.1+ specifications.
RFC 6901: JavaScript Object Notation (JSON) Pointer
IETF standard defining syntax for $ref URI fragment pointers and resolution.
YAML 1.2 Specification Standard
Official specification for YAML Ain't Markup Language data serialization.
17. Frequently Asked Questions (30 FAQs)
Related Tools
Browse all toolsOpenAPI Validator
Validate, lint, and audit OpenAPI 3.2, 3.1, 3.0 and Swagger 2.0 specifications in JSON or YAML. Detect syntax errors, broken $ref pointers, path issues, security vulnerabilities, and API design warnings in your browser.
Postman to OpenAPI
Convert your Postman Collection (JSON v2.0/2.1) to OpenAPI 3.0/3.1 specs instantly. Browser-based, secure, and free. No login required.
OpenAPI Mock Generator
Generate realistic mock API responses from OpenAPI and Swagger specifications. Select an endpoint and response status, resolve schemas and $ref references, customize mock data, and export ready-to-use mock fixtures or server code entirely in your browser.
Free JSON Diff Checker
Compare two JSON files or objects online and find structural differences instantly. Detect added, removed, and modified values with nested key paths in your browser.
Free Online YAML Validator
Free online YAML validator and syntax checker. Check YAML syntax, find indentation and parsing errors, and debug YAML directly in your browser.
JSON Schema Generator
Instantly generate JSON Schema from any JSON payload. Supports Draft 7 and Draft 2020-12 with fast, browser-based processing.
JSON Formatter
Free online JSON formatter, beautifier, and validator. Format, indent, minify, and inspect JSON with real-time syntax error detection in your browser. 100% client-side.
cURL to Code
Convert cURL commands and browser DevTools requests into clean, idiomatic code for JavaScript, Python, Node.js, Go, and PHP. 100% client-side with zero server uploads.