Skip to main content

Tutorial: Compare two OpenAPI Versions

This is a quick tutorial that shows you how two versions of the same OpenAPI file

1. Install the Optic CLI

npm install -g @useoptic/optic

2. Clone the demo repo

git clone https://github.com/opticdev/openapi-demo
cd openapi-demo

3. Use the diff command to compare the two versions of the OpenAPI specification.

optic diff todo-api.yaml todo-api-breaking-change.yaml

In this example there are two changes between the versions:

  • We made status a number instead of a string
  • We have renamed name to message.
GET /todos:
  - response 200:
    - body application/json:
      - field message added
      - field name removed
      - field status
        - schema changed

4. Use the --web flag to visualize the changes

optic diff todo-api.yaml todo-api-breaking-change.yaml --web

alt

Using Optic as you write OpenAPI​

Optic is built to work alongside Git to make it easy to compare OpenAPI versions across branches.

optic diff openapi.yaml --base main --web

base is the branch you want to compare against, usually if you are working on feature branches it will be the name of your default branch.

Add API Diffs to every Pull Request

You can set up Optic Cloud to add these visual changelogs to every Pull Request that changes the API. Get started here