api-diff

# 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

```bash
# 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

```bash
# 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

```json
{
  "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

```yaml
- 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

```bash
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)