Verify OpenAPI accuracy
Update with Traffic

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 spec using Optic

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:// traffic will not be captured unless you first run optic setup-tls and trust Optic's certificate.


If you don't see any traffic being captured, check our client guide for troubleshooting instructions. You may need to change a setting so Optic's system proxy is used.

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:
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
Review API Changes with Optic

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.