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.