Generate OpenAPI
Optic turns network traffic from your browser or your existing integration tests into an accurate OpenAPI documentation. Optic runs every time your code changes to update your OpenAPI spec or verify that it matches the implementation.
Capture traffic
Option 1: Capture traffic from your API
Optic starts a local proxy that 1) forwards traffic to an instance of your API and, 2) compares that traffic to your OpenAPI specification. You need to specify the server's address in the optic.yml
under server.url
. You also need to have your tests send requests through our proxy using the OPTIC_PROXY
environment variable.

To start capturing your test traffic, run:
optic capture init /path/to/openapi.yml
The quickest way to explore Optic is to send mock requests defined in the optic.yml
. We know this won't scale, but you can get it working right away and automate the traffic after you see how Optic works.
capture:
openapi.yml:
# 🔧 Runnable example with simple get requests.
# Run with "optic capture ${oasFile} --update interactive"
# You can change the server and the 'requests' section to experiment
server:
url: https://api.github.com
requests:
send:
- path: /users
method: GET
- path: /orgs/opticdev/repos
method: GET
- path: /orgs/facebook/repos
method: GET
- path: /orgs/github/repos
method: GET
In this example, Optic will send requests to https://api.github.com
and make GET
requests to /users
and some /orgs/{orgId}/repos
. You can change this to run against your API server and pass in a command to start a local server. A full configuration reference can be viewed here.
optic capture openapi.yml --update=interactive
Option 2: Import a Postman collection
Optic learns from the example traffic in your Postman Collection. You can save examples in the Postman Client by clicking Save as Example
button in the bottom right:

optic capture openapi.yml --postman collection.json --update=interactive
Documenting your endpoints
Optic uses real traffic to update API endpoints. You will be asked to approve each path before Optic adds it to your OpenAPI specification. It can usually infer complex paths like /user/{userId}/orders/{orderId}
, but if it gets something wrong you can manually correct it during the interactive flow. You only have to do this once. The more Optic learns about your URL schema the better it gets.
Are some of the paths Optic observed not part of your API? Ie. Images, html, etc? Just add an extension to your OpenAPI file to tell Optic to ignore these paths going forward:
openapi: 3.1.0
x-optic-path-ignore:
- "**/*.+(ico|png|jpeg|jpg|gif)"
- "/health-check"
After approving a few of the new operations Optic observed we can see that it wrote a lot of OpenAPI for us:
Learning path patterns for unmatched requests...
Documenting new operations:
✔ GET /users
✔ GET /orgs/{orgId}/repos
+ 1384 - 0 openapi.yml
Keeping your spec up to date
Now that you have an OpenAPI spec, the challenge is keeping it up to date. Since we already have requests or tests set up, we can verify that the OpenAPI spec matches the traffic it receives (think of this like a snapshot test for your API).
Verify your OpenAPI spec against traffic by running:
optic capture openapi.yml
Optic will check the captured traffic against your OpenAPI spec and highlight any diffs.
We recommend adding this step to your CI pipeline so that you can ensure your OpenAPI spec matches the implementation. If Optic detects that your OpenAPI spec becomes inaccurate, Optic will fail the CI pipeline and let you fix the OpenAPI spec before it lands in your main branch.