Diff and Lint OpenAPI

optic diff

The diff command compares two versions of an OpenAPI specification and then checks for breaking changes, and then applies your spec lint rules and custom style guides.

Test for breaking changes - Unlike most linters, Optic can detect breaking changes between two versions of your API

Forwards only governance - Unlike most linters, Optic won't apply your new linting rules to existing API endpoints. Example: You wouldn't want your team to go rename each field to camelCase because doing so would introduce a ton of breaking changes. Exactly how rulesets are applied can be configured (more below)

Comparing OpenAPI to a previous version in Git (recommended)

optic diff openapi.yml --base main # compare head to tag
optic diff feature/example:openapi.yml develop:main # if you want to compare two tags explicitly

Reads the current version on whichever branch you have open, and compares it to the version of the file on main. This pattern is great for CI / tests.

• base can be a git branch name, tag, or commit.
• --web writes a tmp html file that visualizes the changelog and rule results in the browser

Comparing 2 OpenAPI on the filesystem

optic diff openapi_v0.yml openapi_v1.yml 

Comparing 2 OpenAPI URL

optic diff \
https://raw.githubusercontent.com/opticdev/bookstore-example/89c9a67935c850c1051059f4c719ef433dea8cc0/openapi.yml \
https://raw.githubusercontent.com/opticdev/bookstore-example/ac5f3c55a6f7f27c482a557563686d0328dafb55/openapi.yml