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 https://api.yoursite.com

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

optic update openapi.yml --all

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.

Using the reverse proxy

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

This means instead of sending traffic to https://api.your-service.com, we would send traffic to https://localhost:8000.

# instead of sending this request
curl https://api.your-service.com/users

# 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://api.your-service.com

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]" ...
 

openapi: 3.1.0
x-optic-path-ignore:
- "**/*.+(ico|png|jpeg|jpg|gif)"
- "/health-check"
info:
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