api-diff

name

api-diff

description

Compare two OpenAPI spec files and produce a structured diff report. Use when you need to know what changed between two versions of an API spec, detect breaking changes before releasing a new API version, or check a PR's API spec changes in CI. Triggers include "diff API specs", "compare OpenAPI", "what changed in the API", "check API changes", "API spec diff", "compare swagger files", or any task involving comparing two versions of an OpenAPI or REST API specification.

api-diff

Compare two OpenAPI specs and get a structured list of changes with breaking change classification.

When to use

• Before releasing a new API version, check if any breaking changes were introduced
• In CI to block merges that contain breaking changes
• When reviewing a PR that modifies the OpenAPI spec
• When onboarding to a new API - understand what changed between versions

Diff two files via CLI

# Basic diff - exits 1 if breaking changes found
adc diff api-v1.yaml api-v2.yaml

# Only show breaking changes
adc diff api-v1.yaml api-v2.yaml --only-breaking

# JSON output for scripting
adc diff api-v1.yaml api-v2.yaml --format json

# Diff using stored spec IDs
adc diff --base my-api@1.0.0 --head my-api@1.1.0

Diff via API

# Upload two files
curl -s -X POST http://localhost:3100/api/diff \
  -F "base=@api-v1.yaml" \
  -F "head=@api-v2.yaml" \
  -F "base_label=v1.0.0" \
  -F "head_label=v1.1.0"

# Using stored spec IDs
curl -s -X POST http://localhost:3100/api/diff \
  -H "Content-Type: application/json" \
  -d '{ "base_spec_id": "my-api@1.0.0", "head_spec_id": "my-api@1.1.0" }'

Diff result shape

{
  "summary": { "breaking": 2, "nonBreaking": 3, "informational": 0 },
  "changes": [
    {
      "path": "/paths/~1users~1{id}/get/parameters",
      "type": "parameter-required-added",
      "severity": "breaking",
      "description": "required parameter 'locale' added",
      "before": null,
      "after": { "name": "locale", "in": "query", "required": true }
    
  

CI pipeline usage

- name: Check for breaking API changes
  run: adc diff openapi-main.yaml openapi-pr.yaml
  # exits 1 and fails the step if breaking changes found

Store a spec for repeated diffs

adc specs push openapi.yaml --id my-api --version 1.2.0

Supported formats

• OpenAPI 3.x (YAML or JSON)
• $ref references are automatically resolved before diffing
• Swagger 2.x is not supported (returns an error with a migration hint)