Developer Tool

OpenAPI Diff: Find Breaking Changes

Compare two OpenAPI 3.x specifications (YAML or JSON) and identify breaking changes with a semantic changelog.

Runs in your browser. Nothing is uploaded.
No Changes Specifications are identical
0 Breaking 0 Potentially Breaking 0 Non-Breaking
Old Specification (Base)
0 lines · 0 B
New Specification (Target)
0 lines · 0 B

How to Compare OpenAPI Specifications

Follow these quick steps to audit API changes between two OpenAPI definitions:

  1. Paste or upload your Old Spec: Place your current production OpenAPI document in the left editor.
  2. Paste or upload your New Spec: Place the proposed OpenAPI contract revision in the right editor.
  3. Inspect Changes: Switch to the Changes & Report view to see every modification organized by severity.
  4. Review Breaking Risks: Click any change item to view the exact JSON path, side-by-side snippet diff, and remediation advice.
  5. 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.

Semantic Classification Rules

How API contract changes are classified according to SemVer principles:

🚨 Breaking Changes: Endpoint/Method removed, parameter removed, parameter became required, parameter type narrowed, requestBody became required, response status code removed, schema property removed or data type changed.

⚠️ Potentially Breaking: Enum variant added to response, requestBody removed, operationId renamed, response property made nullable.

✅ Non-Breaking: New endpoint/method added, optional parameter added, new response status code added, property made optional.

Export Changelog & Reports

Keyboard Shortcuts

Ctrl + EnterRun Diff & Switch to Changes Ctrl + Shift + CCopy PR Summary to Clipboard FToggle Fullscreen Focus Mode EscClose modal / Exit Focus Double-click splitterReset layout to 50/50