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.
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
main. You might recognize this syntax as Git
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 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.