Keep your OpenAPI spec and API in sync

Optic makes it easy to document API changes as you work. All you have to do is collect traffic to the API operations that you have been working on, and Optic will figure out which lines of OpenAPI needs to be updated.

First capture traffic from localhost or a development environment

optic capture openapi.yml http://localhost:5001

Then ask Optic to compute the diff and patch any changed operations

optic update openapi.yml --all

Update your OpenAPI using traffic (Step-by-step guide):

1. Capture traffic from your API

Optic can capture traffic from a service you are running locally, or from staging/production. Point Optic at the hostname you want to capture traffic from:

optic capture openapi.yaml https://api.your-service.com

3. Review API diffs

Now that we have captured some traffic, it is time to check for any API diffs. Run the verify command:

optic verify openapi.yaml

 » Verifying API Behavior...
 
 
[ Diff ] 'forks_url' is not documented
operation: get /gists/{gistId}
18 | application/json; charset=utf-8:
19 |   schema:
20 |     type: object
21 |     properties:  Undocumented 'forks_url'
22 |       url:
23 |         type: string
24 |       files:
/Desktop/example/github.yml
fix schema by running $ optic update
 
 
API Behavior Report
 
 Total Requests          : 6
 Diffs                   : 1
 Undocumented operations : 0
 Undocumented bodies     : 0
 

Optic will update your OpenAPI specification with a minimal set of patches.You can review (and even change) the patches Optic applied. The changes are easiest to view in your git client or using Optic's visual changelog:

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

That's it 🚀 Now that your team has an easy way of updating the OpenAPI specification, it's time to set up Optic CI checks to prevent breaking changes and notify consumers about changes.