Skip to main content

Keep OpenAPI up-to-date

10 minutes

Imagine git, but for APIs. Optic makes it easy to keep your OpenAPI spec up-to-date by diffing its current behavior against what is documented, and applying small patches to the specification. It's like having a co-pilot that writes all the boilerplate OpenAPI for you.

What you will need to do this tutorial

  • An OpenAPI 3 or 3.1 file that describes an API
  • A locally running instance of your API that you can call

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 new API operations to the spec by running oas add

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

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}

Update existing API operations by running oas update

oas openapi.yml update --har traffic.har

Optic will make the smallest possible patches to your OpenAPI file. You can go in and edit the OpenAPI manually, add descriptions, etc. Optic will not overwrite the changes you make manually even if you generate new operations or patch existing operations in the future.

If you want to visualize the effective diff remember to try optic diff command:

optic diff openapi.yml --web