Command arguments

All commands accept the these same arguments.

One of the design decisions with openapi-changes was to focus on making it a pure renderer for data captured by libopenapi. In other words, openapi-changes is a front-end for libopenapi, and it comes in four exciting flavours:

A handy Terminal UI
A very sexy and unique Browser UI
A CI/CD friendly Summary Report
A machine-readable JSON Report

The important thing to remember with all four flavors:

They all accept the same arguments.

Local git repository history

If the OpenAPI spec is located in a git repository on the local file system, use two arguments to a command. The first argument is the path to the git repository, and the second argument is the path to the OpenAPI spec file within the repository.

For example if the full path to a spec is: /home/pb33f/corp-code/specs/v3/openapi.yaml

The git repository path is: /home/pb33f/corp-code and the path to the spec file is: specs/v3/openapi.yaml

Some examples:

openapi-changes console ./ specs/v3/openapi.yaml

openapi-changes console \ /home/pb33f/corp-code specs/v3/openapi.yaml

Github repository history

If the OpenAPI spec is located in a git repository on Github, use a single argument, The URL to the spec file on github.

Some examples:

openapi-changes console \ https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml

openapi-changes console \ https://github.com/stripe/openapi/blob/master/openapi/spec3.json

Left and Right file comparison

If you have two OpenAPI files and no github or local git repo available, you can compare a left (original) and a right (modified) pair of OpenAPI specs. This reduces the ‘history’ feature of the tool down to a single commit, but other than that, everything else works, looks and operates the same.

Supply two arguments to any command, both being paths to OpenAPI spec files.

openapi-changes console old-spec.json new-spec.json

openapi-changes console \ /home/pb33f/corp-code/old-spec.json /home/pb33f/corp-code/new-spec.json

Unresolved references

If you have an OpenAPI spec that has unresolved references ($ref) to external files or remote locations in URLs, then you can use the -p / --base flag to specify a base URL or base working directory to use for relative references.

For example if your references are to local files in the same directory, you can use the -p / --base flag to specify the working directory.

openapi-changes console -p . sample-specs/petstorev3.json

If all the references are remote, then use a URL instead:

openapi-changes console -p https://somewhere.megacorp.com sample-specs/petstorev3.json

Command flags

There are two flags that can be used to further customize openapi-changes:

Flag	Short Code	Description
`--no-style`	`-n`	Disable all color output and all terminal styling (useful for CI/CD)
`--top`	`-t`	Only show the latest changes (the last git revision against HEAD)
`--limit`	`-l`	Limit the number of changes to show when using git
`--base`	`-p`	Base URL or Base working directory to use for relative references

For example, to see just the latest changes:

openapi-changes console -t ./ sample-specs/petstorev3.json