Optic makes it easy to adopt OpenAPI in a day, without changing how you work.
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:
Show Optic real API traffic using the
oas capturecommands. Traffic can come from your development environment, tests, or the browser.
Captured traffic is like working copy in Git. Use
oas statusto see the diff between how your OpenAPI specification says your API works, and how it actually works.
oas updateto 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.
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 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.
If you want to add an API operation, use Optic updates your OpenAPI with the new path, operation, and request/response bodies.
oas add to document it:
If you want to update an API operation, use
oas update to patch it:
» GET /todos - 10 patches applied
1 matched / 2 total observed requests
Finished and applied patches
📄️ Optic Proxy
Optic ships with a built-in MITM proxy that you can route traffic through.
📄️ Capture traffic from Chrome
Google Chrome Developer Tools can export a HAR file containing the API requests visible in the Network Tab:
📄️ Traffic inspection toolkits
There are some great open source, free and and paid options
📄️ Add Optic to your tests
Using your API tests as a source of traffic makes it easy to document and maintain an accurate API specification. Many API frameworks / testing tools can export a HAR every time the tests run, which you can pipe into Optic. If your tests show new API operations or changes to existing ones, Optic can detect them, and patch the specification so it is accurate again.