Skip to main content
OASDiff detects breaking changes between OpenAPI and Swagger specifications.

​
Files

OASDiff runs on changed OpenAPI and Swagger specification files that match these patterns:
  • **/openapi.yaml
  • **/openapi.yml
  • **/openapi.json
  • **/swagger.yaml
  • **/swagger.yml
  • **/swagger.json
  • **/*.openapi.yaml
  • **/*.openapi.yml
  • **/*.openapi.json
  • **/*.swagger.yaml
  • **/*.swagger.yml
  • **/*.swagger.json

​
How it works

When a supported specification file changes, CodeRabbit compares the previous version from the pull request base with the changed version and reports breaking API changes found by OASDiff. Findings are posted as review comments with the affected operation, path, section, and OASDiff fingerprint when available. OASDiff findings use these severities:
  • OASDiff error-level breaking changes are reported as errors.
  • OASDiff warning-level breaking changes are reported as warnings.
  • Lower-level findings are ignored by default.

​
Configuration

OASDiff is enabled by default. You can disable it in .coderabbit.yaml:
.coderabbit.yaml
reviews:
  tools:
    oasdiff:
      enabled: false
OASDiff can also use a repository configuration file. CodeRabbit looks for these files, preferring dotfile names first:
  • .oasdiff.yaml
  • .oasdiff.yml
  • .oasdiff.json
  • .oasdiff.toml
  • .oasdiff.hcl
  • oasdiff.yaml
  • oasdiff.yml
  • oasdiff.json
  • oasdiff.toml
  • oasdiff.hcl
If no OASDiff config file is present, CodeRabbit generates a profile-based config for the review.

​
Profiles

  • Chill: Reports higher-confidence breaking changes with reduced noise.
  • Assertive: Reports a broader set of OASDiff warnings and errors.

​
When we skip OASDiff

CodeRabbit skips OASDiff when:
  • The pull request does not change a supported OpenAPI or Swagger specification file.
  • The changed specification file has no previous version in the pull request base.
  • OASDiff is already running in GitHub workflows.

​
What’s next

Buf

Lint Protobuf files for API consistency and style using Buf.

All supported tools

Browse the complete list of linters, security analyzers, and CI/CD integrations available in CodeRabbit.

Configuration reference

Full reference for all available options, including how to enable, disable, and tune individual tools.