What counts as a breaking change?

Removing an endpoint, parameter or response code, making an optional parameter required, or narrowing a response schema.

Yes, local $ref pointers into components are resolved before comparison.

Yes, both inputs accept JSON or YAML.

Is my data uploaded to a server?

No. This tool runs entirely in your browser using standard web APIs, so your input never leaves your device and nothing is logged or stored on our servers.

Does it work offline and on mobile?

Yes. Once the page has loaded it keeps working without a network connection, and the layout is responsive so it stays usable on phones and tablets.

API Breaking Change Detector

Diff two OpenAPI specs and flag breaking changes.

Support

Works Offline

Privacy First

No Login

No API

Baseline spec (old)

The version currently in production

openapi: 3.0.3
info:
  title: Orders API
  version: 1.2.0
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      tags: [orders]
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [id, total]
                  properties:
                    id:
                      type: string
                    total:
                      type: number
    post:
      operationId: createOrder
      summary: Create an order
      tags: [orders]
      responses:
        "201":
          description: Created
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get an order
      tags: [orders]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
        "404":
          description: Not found

Candidate spec (new)

The version you are about to ship

openapi: 3.0.3
info:
  title: Orders API
  version: 1.3.0
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      tags: [orders]
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: status
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [id, total, currency]
                  properties:
                    id:
                      type: string
                    total:
                      type: string
                    currency:
                      type: string
    post:
      operationId: createOrder
      summary: Create an order
      tags: [orders]
      responses:
        "201":
          description: Created
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get an order
      tags: [orders]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
  /refunds:
    post:
      operationId: createRefund
      summary: Create a refund
      tags: [refunds]
      responses:
        "201":
          description: Created

Compatibility report

Breaking changes are anything an existing client could trip over

Breaking

Risky

Additive

POST /refunds—New operation added.
GET /orders—New required query parameter `status` — existing callers will fail.
GET /orders—Response `200 application/json` schema changed. before: [{id?:string,total?:number}] after: [{currency?:string,id?:string,total?:string}]
GET /orders/{orderId}—Response `404` removed.

About the API Breaking Change Detector

Compare an old and a new OpenAPI document to see exactly what changed: removed endpoints, removed or newly required parameters, changed response schemas and deleted status codes are flagged as breaking, while additive changes are listed separately so you can ship with confidence.

Examples

v1 vs v2

Two OpenAPI documents

Output

2 breaking, 1 risky, 5 additive changes

Keyboard shortcuts

Copy the main outputCtrl / ⌘ + Shift + C
Download the resultCtrl / ⌘ + S
Share this toolCtrl / ⌘ + Shift + S
Reset the inputsAlt + R
Open the tool search paletteCtrl / ⌘ + K

Related tools

API Changelog Generator

API & HTTP

Generate a Markdown changelog from two OpenAPI versions.

API Consistency Auditor

API & HTTP

Audit an API for naming, casing and response consistency.

API Contract Analyzer

API & HTTP

Lint an OpenAPI or Swagger spec for contract quality issues.

Postman ↔ OpenAPI Converter

API & HTTP

Convert a Postman collection to OpenAPI 3 and back again.

API Response Schema Generator

API & HTTP

Turn a JSON API response into OpenAPI, JSON Schema or TypeScript.

cURL Command Parser

API & HTTP

Parse a curl command into method, URL, headers, and body.

Frequently asked questions

Postman collections and OpenAPI: two views of the same API
A collection describes calls you make; a spec describes the contract you promise. Here is how to convert between them without losing the parts that matter.

Comments

No login needed. Comments appear after a quick review.

Loading comments…

Version 1.0.0 · Updated 2026-08-20 · Runs entirely in your browser

API Breaking Change Detector

About the API Breaking Change Detector

Examples

Keyboard shortcuts

Related tools

API Changelog Generator

API Consistency Auditor

API Contract Analyzer

Postman ↔ OpenAPI Converter

API Response Schema Generator

cURL Command Parser

Frequently asked questions

What counts as a breaking change?

Does it handle $ref?

Can I use YAML?

Is my data uploaded to a server?

Does it work offline and on mobile?

Read more

Comments