Skip to main content

Diff OpenAPI Versions

OpenAPI specifications are large, complicated and full of internal references. It is difficult to understand how the API is actually changing by looking at the line changes in git.

Optic's diff command loads two OpenAPI files, compares them, and provides a visualization of API changes. Instead of being grouped by file and line (like Git), Optic groups changes by API Operation, request and response.

Running with Git

If you are working on a feature branch in Git, Optic makes it easy to compare your OpenAPI changes to the default branch:

optic diff openapi.yaml --base main

This command compares openapi.yaml on your current branch to the version of openapi.yaml on the main branch.

You can also compare two arbitrary branches by being more explicit:

optic diff feature/1:openapi.yaml main:openapi.yaml

This command compares feature/1 to main. You might recognize this syntax as Git ref:filename format.

Running against two files

If you have two versions of the same OpenAPI file outside of Git, you can run optic diff by inputting two file paths:

optic diff path/to/openapi.yaml path/to/openapi-1.yaml

Visual API Changelogs

For a more detailed view of API Changes, you can include the --web flag. This computes the changelog locally and includes it via a URL to Optic's visual changelog view (we do not save the data).

optic diff openapi.yaml --base main --web
Optic Cloud for API Review

Optic Cloud adds detailed changelogs to Pull Requests that include API Changes. These changelogs help Code Reviewers understand the actual API changes being proposed and leave a more helpful + accurate reviews. You can set up Optic Cloud here.