Generate an OpenAPI Changelog

Optic turns the git history for your OpenAPI spec into a Stripe-style changelog.

optic history openapi.yml

# TodoAPI
### Mon May 22 2023
- added `GET` `/todos/{todoId}/{userId}`
### Tue May 16 2023
- removed `GET` `/todos`
### Thu Jul 21 2022
- `GET` `/todos`:
  - removed `403` response
  - removed `200` response `todos`.`items`.`name` as required
  - added `200` response `todos`.`items`.`message`
  - removed `200` response `todos`.`items`.`name`
  - added `200` response `todos`.`items`.`message`
  - changed the type of `200` response `todos`.`items`.`status`
  - removed `exclude_completed` query parameter
  - removed `category` query parameter

By default, the history command will walk the full history of your OpenAPI spec. This can take a few minutes. If you'd like to limit how far back the changelog goes set the --history-depth flag. In this example the changelog will only include the last 20 revisions to your OpenAPI specification:

optic history openapilyml --history-depth=20

Interactive Changelogs

Optic Cloud tracks every change to your OpenAPI specifications and normalizes the data for quick lookups and comparisons. This means when you push a new version of your API it only has to compute one API diff, not the entire history. Optic Cloud users also get an API interactive changelog.

Setup an interactive changelog

npm install -g @useoptic/optic

optic login

Next, add your APIs to your Optic API hub by running the add command. Use --history-depth=0 to upload the full history.

optic api add openapi.yml --history-depth=0
# or
optic api add ./specs --history-depth=0
# or
optic api add --all --history-depth=0

Always up-to-date

Each time you merge to your default branch, run the push command to upload the latest version to Optic. If there were no changes to the OpenAPI files in the commit, Optic won't upload it.

optic spec push todo-api.yaml --tag main

If you are using the Optic GitHub/GitLab Action this happens automatically and doesn't need to be manually setup.