Compare OpenAPI Specs Online
Paste two OpenAPI or Swagger specifications. See which endpoints, schemas, and parameters changed.
🔒 100% private — runs entirely in your browseror try sample data
Paste two OpenAPI or Swagger specifications. See which endpoints, schemas, and parameters changed.
🔒 100% private — runs entirely in your browseror try sample data
OpenAPI Diff compares two OpenAPI (Swagger) specifications and shows you exactly which endpoints, schemas, parameters, and responses changed. It's essential for detecting breaking changes, reviewing API version bumps, and validating contract compatibility between services.
API specifications are contracts between services. When a spec changes — a required field is added, a response schema is restructured, or an endpoint is removed — downstream clients can break. Comparing specs side by side before publishing a new version catches breaking changes early.
Paste your OpenAPI 3.x or Swagger 2.0 specs in JSON format. The tool performs deep structural comparison, surfacing changes at every level — from top-level info and paths down to individual schema properties and enum values. Everything runs client-side — your API contracts stay private.
// Version 1: email is optional
"User": { "required": ["id", "name"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }
} // Version 2: email is now required (BREAKING!)
"User": { "required": ["id", "name", "email"], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }
}Adding a field to required is a breaking change for clients that don't send it. The diff highlights this as a modified array.
// v1: Returns array directly
"responses": { "200": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } }
} // v2: Wraps in pagination object (BREAKING!)
"responses": { "200": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { ... } }, "next_cursor": { "type": "string" } } } }
}Changing a response from array to object breaks all existing clients. The diff makes this structural change obvious.
// Comparing specs shows new paths added:
// + /users/{id} (GET - get user by ID)
// These are non-breaking additions but should
// still be reviewed for correct parameter types,
// response schemas, and error handling.New endpoints are safe additions but verify they follow existing conventions (pagination, error format, auth).
OpenAPI specs use $ref for shared schemas. This tool compares the raw JSON, so $ref values are compared as strings. If one spec inlines a schema while the other uses $ref, they'll appear different even if they resolve to the same schema. Resolve refs before comparing for a more accurate diff.
In OpenAPI 3.0, nullable: true and omitting a field from required are different things. A field can be required but nullable (must be present, but can be null). Changing either one independently can break clients differently.
Not all changes are breaking: adding optional fields, new endpoints, or new enum values are generally safe. Removing fields, adding required fields, changing types, or removing endpoints are breaking. The diff shows all changes — it's up to you to classify which are breaking for your consumers.
Paste your OpenAPI specifications in JSON format into the two panels and click Compare. The tool performs deep structural comparison and highlights every changed path, schema, parameter, and response.
Yes. The diff highlights changes like removed endpoints, new required fields, modified response schemas, and changed parameter types — all common sources of breaking changes. You'll need to evaluate each change in context.
Yes. The tool compares any valid JSON structure, so both OpenAPI 3.x and Swagger 2.0 specs in JSON format work. It won't convert between formats — compare like-with-like.
This tool expects JSON input. Convert your YAML spec to JSON first using a tool like yq or an online YAML-to-JSON converter, then paste the JSON here.
Yes. This tool runs entirely in your browser. Your OpenAPI specifications, including any server URLs, authentication schemes, or internal endpoint details, are never sent to any server.
Yes. You can compare individual sections (just the paths, just the schemas, etc.) by pasting only the relevant JSON. The tool compares whatever JSON you provide.