The easiest way to use OpenAPI

Track your API changes without writing YAML by hand.

npmGitHub Repo stars
Install the developer CLI $ npm -g install @useoptic/optic Collect API Traffic $ optic capture openapi.yml
23 requests captured
» Verifying API behavior...
Make the OpenAPI match the traffic $ optic update openapi.yml --all
"Brilliant! That's a whole lot of OpenAPI I don't need to write, and Optic is even making components to keep your OpenAPI Dry."
Phil Sturgeon APIs You Won't Hate
npm install -g @useoptic/optic

How it works

The Optic CLI is like Git, but for your APIs. When you make changes to your API, Optic makes it easy to correctly update the OpenAPI.

  1. Capture traffic from localhost, production, or your development environment:
optic capture openapi.yml
  1. Run optic update to update your spec to match the traffic. Optic makes surgical patches the same way a developer would:
optic update openapi.yml --all
API Diff:
[ Diff ] 'forks_url' is not documented
operation: get /gists/{gistId}
18 | application/json; charset=utf-8:
19 |   schema:
20 |     type: object
21 |     properties:  Undocumented 'forks_url'
22 |       url:
23 |         type: string
24 |       files:
type: object
+    forks_url:
+      type: string

Review OpenAPI Changes

Figuring out what has changed between two versions of an OpenAPI spec is almost impossible, even for experts. This is because changing one line can affect dozens of endpoints. Optic changelogs show an API diff making it easy for anyone to understand review the API changes.

Diff OpenAPI across Git branches $ optic diff openapi.yml --base main Catch breaking changes by including the --check flag $ optic diff openapi.yml --base main --check Visual changelogs for easier review using --web flag $ optic diff openapi.yml --base main --web

🚀 What's different?

Optic patches existing specs (it's not a generator)

Instead of regenerating your entire spec, Optic patches existing OpenAPI files just like a developer writing OpenAPI would. Your spec will look the same way it did before, but with the new stuff added.

Supports $ref and multiple files

Optic always updates the correct $ref in the correct file. Some users have their spec spread across 100s of files and Optic patches it in the right spots.

Never overwrites description, summary or the docs your team wrote

Most OpenAPI generators are one-shot meaning regenerating the spec will remove any manual additions you made. Optic is not like that. You can collaborate it on an on-going basis to keep your specs up-to-date and it will never overwrite manual changes

Generates components for shared Schemas and uses $ref

Optic gives you a spec your team can actually maintain. Schemas that appear across multiple endpoints will be turned into components.


Try the Optic CLI

npm install -g @useoptic/optic