How to Validate OpenAPI Contracts With Optic and oasdiff

Optic and oasdiff enforce the OpenAPI contract in CI: Optic checks changes against captured traffic and rules, and oasdiff diffs two specs for breaking changes.

Run optic diff on the pull request to compare the spec against the base and against real captured traffic, and use oasdiff when you just need a spec-to-spec diff or breaking-change report.

Steps

• Add the spec to the repo and a CI job on pull_request.
• Run optic diff against the base ref with --check.
• Optionally run oasdiff breaking as a second, tool-independent gate.

Optic check

on: [pull_request]
jobs:
  api-contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npx @useoptic/optic diff openapi.yaml --base origin/${{ github.base_ref }} --check

Gotchas

• Optic needs git history for the base ref, so set fetch-depth: 0 on checkout.
• Spec validation proves the document is compatible, not that the server matches it; pair it with drift detection.

Related guides