usefulweb.site OpenAPI Diff Explorer

Developer & cloud explorers

OpenAPI Diff Explorer

Compare two versions of an OpenAPI spec and see exactly which changes break clients.

Try an example: Shop API v1 → v2

How it works

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).

  • 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.

For scripts and AI agents

  • JSON API: POST https://openapidiffexplorer.usefulweb.site/api/v1/calculate (same calculation as this page)
  • Interface description: OpenAPI 3.1 · AI guide: llms.txt
  • MCP server (Streamable HTTP): https://openapidiffexplorer.usefulweb.site/mcp · tool name openapi_diff_explorer
Example request
curl -s -X POST https://openapidiffexplorer.usefulweb.site/api/v1/calculate \
  -H 'content-type: application/json' \
  -d '{…see OpenAPI examples…}'

Related tools

Feedback