Track changes with OpenAPI

Wouldn't it be nice if updating OpenAPI specifications was as easy as tracking changes in Git? Any developer should be able to write down the API changes so their teammates can review the changes and give feedback early. With Optic it takes three minutes to accurately patch an OpenAPI specification to reflect recent changes.

Need help creating your team's first OpenAPI specification? Check out our guide to documenting existing services

1. Capturing traffic

Optic compares your API's actual behavior to what is documented in the OpenAPI specification. Point Optic at the modified version of your API running locally or a development environment.

Capturing traffic to localhost:

optic oas capture openapi.yaml localhost:4000

Capturing traffic to your development environment:

optic oas capture openapi.yaml https://developer123.api.example.dev

Client Compatibility

Most clients work out of the box (✅) or after minor tweaks to their settings (🟡)

HTTP/s Client	Compatibility	Steps to capture traffic
Chrome	✅
Safari	✅
Postman	✅ (defaults)	Tell Postman to use System proxy
Insomnia	✅ (defaults)	Tell Insomnia to use System proxy
Paw	✅ (defaults)	Tell Paw to use System proxy
Httppie	🟡	Tell httppie to use the Optic Proxy
curl	🟡	set `HTTP_PROXY` and `HTTPS_PROXY` in the environment before running curl commands
newman	🟡	set `HTTP_PROXY` and `HTTPS_PROXY` in the environment before running curl commands
Firefox	🟡	Firefox detects the MITM proxy and blocks it by default. 1) Navigate Firefox to the API host you want to capture from and "Accept" the Security Risk. For `localhost` captures set the netowrk option `network.proxy.allow_hijacking_localhost` to `true`

Common issue: TLS traffic is not being captured?

The Optic CLI will not be able to learn from TLS encrypted traffic unless you trust its certificate. The command will guide you through the instructions for trusting the certificate on your operating system:

This allows the Optic proxy to man-in-the-middle your TLS traffic when the capture command is running. An intruder would need pretty deep access to your machine to exploit this. Our code is open source and we encourage people working with sensitive APIs to use development environments.

optic oas setup-tls

Capturing test traffic

Optic can intercept traffic from your tests, provided they are sent over the network. When you run capture with --command flag the proxy will start and then run the command provided with HTTP_PROXY and HTTPS_PROXY injected into the environment:

optic oas capture openapi.yaml <target-url> --command <your-test-command>

If your tests do not run over the network, many frameworks have HAR logging libraries you can use to capture a HAR and pass it into Optic directly verify --har logs.har.

3. Run `optic oas verify` (think of this like `git status`)

optic oas verify openapi.yaml

Optic will list all the diffs it observed between your OpenAPI specification and the traffic it collected:

[ 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
  (use "--patch" to update)

After processing all the traffic, Optic will print a final report with a total diff count, and an API coverage report (which parts of your API were covered by traffic). If you have high coverage, and no diffs, that's a very strong signal that your API is working as-designed.

API Behavior Report

 Total Requests          : 6
 Diffs                   : 7
 Undocumented operations : 0
 Undocumented bodies     : 0

Coverage Report 92.3%
 ●●●●   get /gists/{gistId}
   12    200
 ●●●◌   get /users
   10   200
 ●●◌◌   get /users/{user}/starred/{owner}/{repo}
    6   200 404
 ●●◌◌   get /users/{user}/followers
    6   200
 ●◌◌◌   get /users/{user}/subscriptions
    1   200
 ●◌◌◌   get /users/{user}/gists
    1   200

As you review the diffs, decide whether each diff was caused by an intentional or accidental change (returning debug data in a response). If you made any accidental changes to the API behavior go fix the code so they do not end up getting released. Then run the clear command to reset the traffic sampling:

optic oas clear openapi.yaml

Restart the API and capture more traffic:

optic oas capture openapi.yaml localhost:4000

Repeat this until you see only the changes you planned to make in the report.

4. Patch the OpenAPI specification

Now run verify with the --patch flag to update the specification.

optic oas verify openapi.yaml --patch

If you want to document new operations use --document all or --document "[method] /path".

optic oas verify openapi.yaml --document "patch /resource/{resourceId}/settings"

You should see Optic's patches appearing in your OpenAPI files. You can review these in your favorite git client, edit them, and then check the changes in. Hopefully that made your team's process for updating the OpenAPI specification a lot easier and much more accurate.

Need help?

Hopefully the tools just-work, but we are around to help if you have trouble. We want to make these tools easy to use and powerful -- please ask us for help if you have trouble so we can improve the tools for everyone.

1. Capturing traffic​

Client Compatibility​

Capturing test traffic​

3. Run optic oas verify (think of this like git status)​

4. Patch the OpenAPI specification​