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

From: Turn HTTP Traffic into OpenAPI with Optic (opens in a new tab)

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

2. 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

[ 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:

schema:
type: object
properties:
+    forks_url:
+      type: string
files:

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.

🚀 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.

components:
  UserResponse:
    ...
  ProfileConfiguration:
    ...

What can you do with your new OpenAPI spec? Ship amazing APIs