# OpenAPI Diff Explorer

> Compare two versions of an OpenAPI spec and see exactly which changes break clients. Paste or link two OpenAPI 3.x (or Swagger 2) documents in JSON or YAML. Every operation, parameter, request body, response and schema property is compared (with $ref resolution), and each change is classified as breaking, potentially breaking or non-breaking, with the direction-aware rules API teams use (e.g. a new required request field breaks clients; a new response field does not; a new response enum value might).

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://openapidiffexplorer.usefulweb.site/ (interactive tool at https://openapidiffexplorer.usefulweb.site/tool)
- JSON API: POST https://openapidiffexplorer.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://openapidiffexplorer.usefulweb.site/api/v1/tool)
- OpenAPI: https://openapidiffexplorer.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://openapidiffexplorer.usefulweb.site/mcp - tool `openapi_diff_explorer`

## Inputs
- oldSpec (textarea): Old spec (JSON or YAML)
- newSpec (textarea): New spec (JSON or YAML)
- oldUrl (url): Or: URL of the old spec
- newUrl (url): Or: URL of the new spec

## Method
- Operations are matched by method + path; paths that differ only in parameter names ({id} vs {orderId}) are treated as the same operation.
- Request side (parameters, bodies): removing accepted values, adding required inputs, tightening limits or changing types is breaking.
- Response side: removing properties or success responses, or making a guaranteed field optional, is breaking; new enum values, new nullability and new success codes are potentially breaking; additions are non-breaking.
- Local $refs are resolved (cycles detected). Removed operations and changed security requirements are breaking.
- Semver advice: any breaking change → major; additions only → minor; otherwise patch.