Usage Examples

OpenAPI diff of local files in YAML

oasdiff diff data/openapi-test1.yaml data/openapi-test2.yaml

The default diff output format is YAML.
No output means that the diff is empty, or, in other words, there are no changes.

OpenAPI diff of local files in Text/Markdown

oasdiff diff data/openapi-test1.yaml data/openapi-test2.yaml -f text

The Text/Markdown diff report provides a simplified and partial view of the changes.
To view all details, use the default format: YAML.
If you'd like to see additional details in the text/markdown report, please submit a feature request.

OpenAPI diff of local files in HTML

oasdiff diff data/openapi-test1.yaml data/openapi-test2.yaml -f html 

The HTML diff report provides a simplified and partial view of the changes.
To view all details, use the default format: YAML.
If you'd like to see additional details in the HTML report, please submit a feature request.

OpenAPI diff for remote files over http/s

oasdiff diff https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml -f text

Breaking changes

oasdiff breaking https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml

Breaking changes as YAML

oasdiff breaking https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml -f yaml

Breaking changes across multiple specs with globs

oasdiff breaking "data/composed/base/*.yaml" "data/composed/revision/*.yaml" -c

Fail with exit code 1 if any ERR-level breaking changes are found

oasdiff breaking "data/composed/base/*.yaml" "data/composed/revision/*.yaml" -c -o ERR

Fail with exit code 1 if any change is found

oasdiff diff https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml -f text -o

OpenAPI changelog

oasdiff changelog https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml

OpenAPI changelog with custom template

oasdiff changelog base.yaml revision.yaml --template my-template.md -f markdown
oasdiff changelog base.yaml revision.yaml --template my-template.html -f html

See CHANGELOG-TEMPLATE.md for full documentation and examples.

Side-by-side review in your browser

oasdiff changelog HEAD~1:openapi.yaml HEAD:openapi.yaml --open
oasdiff breaking HEAD~1:openapi.yaml HEAD:openapi.yaml --open

After printing the changelog, encrypts the comparison on your machine, uploads only the ciphertext to oasdiff.com, and opens the rendered side-by-side review in your browser. No sign-in: the decryption key stays in the review link's # fragment and is never sent to our servers. The link works for 7 days and is shareable with anyone (the key is part of it). See BREAKING-CHANGES.md for the full flow.

OpenAPI diff for endpoints containing "/api" in the path

oasdiff diff https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml -f text -p "/api"

Filters are applied recursively at all levels. For example, if a path contains a callback, the filter will be applied both to the path itself and to the callback path. To include such a nested change, use a regular expression that contains both paths, for example --match-path "path|callback-path".

Exclude paths and operations with extension "x-beta"

oasdiff diff https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml -f text --filter-extension "x-beta"

Notes:

1. OpenAPI Extensions can be defined both at the path level and at the operation level. Both are matched and excluded with this flag.
2. If a path or operation has a matching extension only in one of the specs, but not in the other, it will appear as Added or Deleted.

Ignore changes to description and examples

oasdiff diff data/openapi-test1.yaml data/openapi-test3.yaml --exclude-elements description,examples -f text

Display change summary

oasdiff summary https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml

OpenAPI Diff with Docker

To run with docker just replace the oasdiff command by docker run --rm -t tufin/oasdiff, for example:

docker run --rm -t tufin/oasdiff diff https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml -f text

Breaking changes with Docker

docker run --rm -t tufin/oasdiff breaking https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/oasdiff/oasdiff/main/data/openapi-test3.yaml

Comparing local files with Docker

docker run --rm -t -v $(pwd)/data:/data:ro tufin/oasdiff diff /data/openapi-test1.yaml /data/openapi-test3.yaml

Replace $(pwd)/data by the path that contains your files.
Note that the spec paths must begin with /.

Passing arguments from a script or CI

When base and revision come from variables rather than being typed by hand, put -- after the flags so their values are always read as arguments and never as flags:

oasdiff breaking $flags -- "$base" "$revision"

Note the ordering: -- must come after the flags. Everything following it is treated as a positional argument, so any flag placed after -- is read as a spec instead.

This applies to every input type — local files, URLs, and git revisions alike. Without --, a value that begins with - is parsed as an oasdiff flag, and a value that happens to match a real flag name changes what the command does.