oasdiff

https://www.oasdiff.com/docs
Admin
oasdiff is an OpenAPI comparison tool that detects breaking changes, validates specifications, and...
Tokens:20,942
Snippets:223
Trust Score:7.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install oasdiff with Homebrew

Source: https://www.oasdiff.com/docs

Install oasdiff on macOS or Linux using Homebrew.

```bash
brew install oasdiff
```

--------------------------------

### Install oasdiff with curl

Source: https://www.oasdiff.com/docs

Install oasdiff on macOS or Linux using the curl installer script.

```bash
curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh
```

--------------------------------

### Generate full changelog across microservices with --composed

Source: https://www.oasdiff.com/docs/microservices

Use this command to get the full list of changes (not just breaking ones) across the microservices set. The same --composed flag and quoted globs apply as in the breaking comparison.

```bash
oasdiff changelog --composed "base/*.yaml" "revision/*.yaml"
```

--------------------------------

### MCP server URL

Source: https://www.oasdiff.com/docs/mcp

The hosted oasdiff MCP server endpoint over Streamable HTTP. No install or API key required.

```text
https://api.oasdiff.com/mcp
```

--------------------------------

### GitHub Action workflow for breaking check with auto-upgrade

Source: https://www.oasdiff.com/docs/openapi-31-migration

Example GitHub Actions workflow that uses the oasdiff breaking action with auto-upgrade enabled. The action picks up the flag automatically from the .oasdiff.yaml file.

```yaml
# .github/workflows/oasdiff.yaml
- uses: oasdiff/oasdiff-action/breaking@v0
  with:
    base: 'origin/${{ github.base_ref }}:openapi.yaml'
    revision: 'HEAD:openapi.yaml'
```

--------------------------------

### Check for breaking changes with oasdiff breaking --fail-on ERR

Source: https://www.oasdiff.com/docs/monitor-external-apis

Run oasdiff breaking to get only the changes that would break your integration, with a non-zero exit code for automation.

```bash
# Just the breaking changes, with a non-zero exit code you can act on
oasdiff breaking baseline.yaml https://api.example.com/openapi.yaml --fail-on ERR
```

--------------------------------

### Open side-by-side review with --open

Source: https://www.oasdiff.com/docs/microservices

Adds the --open flag to the changelog command to render changes across every service as a side-by-side review in the browser. Each change is grouped under the service and source block it came from.

```bash
oasdiff changelog --composed "base/*.yaml" "revision/*.yaml" --open
```

--------------------------------

### Open side-by-side review with oasdiff

Source: https://www.oasdiff.com/docs

Open a full side-by-side review of two specs in the browser, with the diff anchored at each change. The link works for 7 days.

```bash
oasdiff changelog HEAD~1:openapi.yaml HEAD:openapi.yaml --open
```

--------------------------------

### .oasdiff.yaml configuration file

Source: https://www.oasdiff.com/docs/github-action

Configuration file at the repo root that the action automatically picks up. It sets fail-on to ERR, excludes description/title/summary elements, and specifies an error-ignore file. Action with: inputs override these values.

```yaml
# .oasdiff.yaml at the repo root
fail-on: ERR
exclude-elements:
  - description
  - title
  - summary
err-ignore: ./oasdiff-err-ignore.txt

```

--------------------------------

### Save baseline and view changelog with oasdiff

Source: https://www.oasdiff.com/docs/monitor-external-apis

Save a baseline snapshot of the provider's spec with curl, then run oasdiff changelog to see what changed since the baseline.

```bash
# Save a baseline snapshot of the provider's spec
curl -sSL https://api.example.com/openapi.yaml -o baseline.yaml

# Later, see exactly what changed since the baseline
oasdiff changelog baseline.yaml https://api.example.com/openapi.yaml
```

--------------------------------

### Run oasdiff breaking with Docker

Source: https://www.oasdiff.com/docs

Run a breaking change check using Docker, mounting the current directory to /specs.

```bash
docker run --rm -v $(pwd):/specs tufin/oasdiff breaking /specs/base.yaml /specs/revision.yaml
```

--------------------------------

### Configure oasdiff MCP server in Cursor

Source: https://www.oasdiff.com/docs/mcp

Adds the oasdiff MCP server to Cursor's mcp.json configuration. Use the global file or the per-project file.

```json
{
  "mcpServers": {
    "oasdiff": {
      "url": "https://api.oasdiff.com/mcp"
    }
  }
}
```

--------------------------------

### oasdiff GitHub Action workflow (pr-comment)

Source: https://www.oasdiff.com/docs/enterprise

Workflow YAML for the oasdiff Action. Runs on pull requests to main, checks out the repo, fetches the base branch, and runs the pr-comment action with the base and revision OpenAPI specs. Requires an OASDIFF_TOKEN repository secret containing your tenant ID. Replace openapi.yaml with your spec path.

```yaml
name: oasdiff
on:
  pull_request:
    branches: [ "main" ]
jobs:
  pr-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - run: git fetch --depth=1 origin ${{ github.base_ref }}

      - uses: oasdiff/oasdiff-action/pr-comment@v0
        with:
          base: 'origin/${{ github.base_ref }}:openapi.yaml'
          revision: 'HEAD:openapi.yaml'
          oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}

```

--------------------------------

### Generate Markdown and HTML changelogs with oasdiff -f

Source: https://www.oasdiff.com/docs/monitor-external-apis

Produce a changelog in Markdown or HTML format that you can publish, attach to a ticket, or commit to a repo.

```bash
# A changelog you can publish or attach: Markdown or HTML
oasdiff changelog baseline.yaml https://api.example.com/openapi.yaml -f markdown > changelog.md
oasdiff changelog baseline.yaml https://api.example.com/openapi.yaml -f html > changelog.html
```

--------------------------------

### Compare breaking changes across microservices with --composed

Source: https://www.oasdiff.com/docs/microservices

Use this command to compare two sets of OpenAPI specs (e.g., base and revision) as a single API. The --composed flag enables multi-file comparison, and the globs must be quoted so the shell passes the * to oasdiff.

```bash
oasdiff breaking --composed "base/*.yaml" "revision/*.yaml"
```

--------------------------------

### GitHub Actions workflow for oasdiff Pro review and merge gate

Source: https://www.oasdiff.com/docs/setup

Create .github/workflows/oasdiff.yml with this content. Set the path to your OpenAPI spec (e.g., api/openapi.yaml) and the snippet updates to match. The permissions block lets the action post the review comment and set the oasdiff merge-gate status with the workflow's built-in GITHUB_TOKEN.

```yaml
name: oasdiff

# On every pull request, oasdiff posts an encrypted side-by-side review
# comment and sets the "oasdiff" merge gate.
on:
  pull_request:
    branches: [ "main" ]

permissions:
  pull-requests: write   # post the review comment
  statuses: write        # set the merge-gate commit status

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: oasdiff/oasdiff-action/changelog@v0
        with:
          base: 'origin/${{ github.base_ref }}:openapi.yaml'
          revision: 'HEAD:openapi.yaml'
          oasdiff-token: ${{ secrets.OASDIFF_TOKEN }}
          github-token: ${{ github.token }}

```

--------------------------------

### Configure auto-upgrade in .oasdiff.yaml

Source: https://www.oasdiff.com/docs/openapi-31-migration

Set auto-upgrade: true in an .oasdiff.yaml file to canonicalise both base and revision to the latest 3.x before diffing, filtering out dialect rewrites. The fail-on: ERR setting is also shown.

```yaml
# .oasdiff.yaml
fail-on: ERR
auto-upgrade: true
```

--------------------------------

### Generate full diff with oasdiff

Source: https://www.oasdiff.com/docs

Generate a full diff of the API definition, including documentation-only edits.

```bash
oasdiff diff base.yaml revision.yaml
```

--------------------------------

### GitHub Actions workflow for daily provider API changelog

Source: https://www.oasdiff.com/docs/monitor-external-apis

A GitHub Actions workflow that fetches the provider's spec daily, and when it changes, commits a dated Markdown changelog and advances the baseline.

```yaml
name: provider-api-changelog
on:
  schedule:
    - cron: "0 8 * * *"      # daily at 08:00 UTC
  workflow_dispatch:
permissions:
  contents: write            # commit the changelog back to the repo
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Fetch the provider's current spec
        run: curl -sSL https://api.example.com/openapi.yaml -o latest.yaml
      - name: On a change, write a dated Markdown changelog and commit it
        run: |
          if cmp -s baseline.yaml latest.yaml; then echo "No change."; exit 0; fi
          mkdir -p changelog
          docker run --rm -v "$PWD:/w" -w /w tufin/oasdiff changelog baseline.yaml latest.yaml -f markdown > "changelog/$(date +%F).md"
          cp latest.yaml baseline.yaml
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add baseline.yaml changelog/
          git commit -m "Provider API change $(date +%F)"
          git push
```

--------------------------------

### Connect oasdiff MCP server in Claude Code

Source: https://www.oasdiff.com/docs/mcp

Adds the oasdiff MCP server to Claude Code using the HTTP transport.

```bash
claude mcp add --transport http oasdiff https://api.oasdiff.com/mcp
```

--------------------------------

### Generate changelog with oasdiff

Source: https://www.oasdiff.com/docs

Generate a changelog of changes that can affect API consumers (breaking + non-breaking).

```bash
oasdiff changelog base.yaml revision.yaml
```
Tokens:
Raw