Skip to main content

Generate OpenAPI from traffic

30 minutes

Turn actual API-traffic into an OpenAPI specification for your service. Optic won't just generate the spec once, it can also help you keep it up-to-date. The tool will never overwrite manual changes you make.

What you will need to do this tutorial

  • A locally running instance of your API that you can call

Create an empty OpenAPI file

oas new openapi.yml

Capture Traffic with Optic's Proxy or other methods

oas capture --proxy http://localhost:3000 > traffic.har

This command will start a proxy on :8000 which will append traffic to a HAR file as it forwards it along to your service.

Run oas status to compute diffs between the spec and the actual API behavior

oas openapi.yml status --har traffic.har

Add API operations to the spec by running oas add

insert your own method / path that you want Optic to document

oas openapi.yml add --har traffic.har GET /lists

Open the OpenAPI file in a text editor and you will notice Optic documented the entire Operation for you.

The add command also supports adding multiple paths at once:

oas openapi.yml add --har traffic.har GET /lists, POST /todos

and parameterized paths:

oas openapi.yml add --har traffic.har GET /lists/{listId}

Once you're done adding all the paths, you can check in your new OpenAPI spec and share it with your team. OpenAPI can be difficult to keep up-to-date and review during code reviews. Luckily Optic can help you update the spec as your API changes, and review API changes visually.