Skip to main content

OpenAPI CLI

Optic makes it easy to adopt OpenAPI in a day, without changing how you work.

npm install -g @useoptic/optic

How Optic helps you adopt OpenAPI

Imagine Git, but for tracking your API changes. When you add a new endpoint run oas add, when you make changes run oas update. Writing OpenAPI manually, and keeping that specification up-to-date should be as easy as tracking changes to our code.

Tracking changes with Optic:

  1. Show Optic real API traffic using the oas capture commands. Traffic can come from your development environment, tests, or the browser.

  2. Captured traffic is like working copy in Git. Use oas status to see the diff between how your OpenAPI specification says your API works, and how it actually works.

  3. Run oas add and oas update to update the spec. Optic precision patches your OpenAPI file with the same additions, updates, and removals you would manually write. This is faster and much less error-prone than writing OpenAPI by hand.

A collaborator, not a generator

Using the CLI to update your spec is like working with a collaborator. It helps you write all the boilerplate OpenAPI and keep your spec in sync with the actual API's behavior.

Never overwrites changes developers make to the same OpenAPI file

Respects $refs across multiple files

Improves accuracy of your specification

Speeds up your team

Using the CLI

First collect some traffic from your API using oas capture

oas capture --proxy localhost:3000 traffic.har

Then run oas status

oas openapi.yaml status --har traffic.har

This command looks at your captured traffic and matches it against your OpenAPI file. The output shows you how requests match up to existing API Operations, as well as paths and methods that have undocumented thus far.


Matched Operations
==================
GET /todos
GET /todos/{todoId}
PATCH /todos/{todoId}/status

Undocumented methods
====================
POST /todos

Undocumented paths
==================
GET /lists

If you want to add an API operation, use oas add to document it:

oas openapi.yaml add --har traffic.har  GET /lists
Optic updates your OpenAPI with the new path, operation, and request/response bodies.

If you want to update an API operation, use oas update to patch it:

oas openapi.yaml update --har traffic.har 
» GET /todos - 10 patches applied

1 matched / 2 total observed requests
Finished and applied patches

Read the full documentation for all CLI commands here.

Capture Methods