Generate from Traffic

Generate an accurate OpenAPI using Traffic

Writing an OpenAPI specification from scratch is a near-impossible task. With Optic you can quickly bootstrap an accurate specification by collecting real API traffic and generating documentation from it.

First capture traffic

optic capture openapi.yml

Then have Optic add all of the observed API Operations to the spec

optic update openapi.yml --all
Documenting an API from traffic

Document your API in 10 minutes (Step-by-step guide)

1. Create an empty OpenAPI file.

Optic does not generate OpenAPI, it patches existing specifications. This allows to use Optic again whenever you add new functionality to your API or change existing endpoints. The new command will write an empty OpenAPI spec to disk.

optic new openapi.yaml

2. Capture traffic from your API

Optic can capture traffic from a service you are running locally, or from staging/production.


There are two ways to run Optic's capture flow, as a reverse-proxy or as a system-proxy. We recommend using the reverse-proxy when using curl, or any tool you can control which url requests go to and the system-proxy for when you cannot (e.g. when using the browser).

Using the reverse proxy

optic capture openapi.yaml --reverse-proxy
Optic proxy is running at https://localhost:8000. Route traffic through it and traffic to will be captured

This means instead of sending traffic to, we would send traffic to https://localhost:8000.

# instead of sending this request

# we would send this request instead
curl https://localhost:8000/users

Using the system proxy

Point Optic at the hostname you want to capture traffic from and then navigate to your website which calls your API.

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 observed API operations

Now that we have captured some traffic, it is time to document our API's operations. Run the verify command:

optic verify openapi.yaml

Optic detects undocumented operations:

You can see Optic tried to infer which parts of each path were variables. If it got anything wrong you should manually tell Optic to document those operations. The more operations you document, the more accurate Optic gets at inferring the paths.

 » Verifying API Behavior...
 [ Undocumented ]    get  /todos/{todoId}/status
 [ Undocumented ]  patch  /todos/{todoId}/status
 [ Undocumented ]   post  /todos/{todoId}
 [ Undocumented ]  patch  /user/profile/settings
 Document all new operations with $ optic update openapi.yaml --all
 Document individual operations with $ optic update openapi.yaml "[method] /[path]" ...

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
- "**/*.+(ico|png|jpeg|jpg|gif)"
- "/health-check"
title: Our Service
version: 1.0.0

4. Start documenting operations

Just like you run git add to track a new file in your codebase, you can start tracking API operations by having Optic add them to your OpenAPI spec.

To document a single operation run:

optic update openapi.yaml "get /todos/{todoId}"

To document all the operations Optic observed run:

optic update openapi.yaml --all

That's it! You can manually go into your OpenAPI file and make changes. Optic will never overwrite them, even if you come back and document more endpoints later.

5. Share with your team

You can use Optic Cloud to host internal API docs and share them with your team. As your API changes Optic will show developers API changelogs and even notify consumers of changes that affect them.

1. First login

optic login

2. Start tracking this API spec in Optic Cloud

Optic will upload your specification and track every version to each operation (like GitHub shows you file history). You can share the link to the documentation with your team 🚀 and they can even subscribe to changes:

optic api add openapi.yaml