Get Started with Optic

Optic helps you get the benefits of OpenAPI without slowing you down. Our CI tool makes it easy for developers to publish accurate API docs, avoid breaking changes, and ship high-quality APIs.

Install

npm install -g @useoptic/optic

Try locally

You need to have at least one OpenAPI specification in your repository. If you need help documenting your API, use Optic to generate an OpenAPI. You can also try Optic in our example repository (opens in a new tab).

optic run

Optic matched 2 OpenAPI specification files:
openapi.yaml, todo-api.yaml.
 
 
| Optic Bookstore Demo Spec (openapi.yml)
| ✅ No breaking changes ✅ Design
| View report: https://app.useoptic.com/@optic/example-api/123
 
 
| TodoAPI (openapi.yml)
| ✅ No breaking changes ✅ Design
| View report: https://app.useoptic.com/@optic/example-api/123

Optic looks at recent API changes and makes sure there are no breaking changes and your design standards are followed.

Since this is your firs time running Optic, it pushes the first version of your OpenAPI specifications to your cloud account. As your API changes, Optic will automatically update the documentation and generate a daily changelog.

Make a breaking change

Make a change to one of your OpenAPI specs. You could try a breaking change such as removing an endpoint or making an optional request parameter required.

This time optic run will show you an error:

| Optic Bookstore Demo Spec (openapi.yml)
| ❌ 1 breaking change ✅ Design
| View report: <Link to web report>

The visual changelog shows the breaking change with an error message in the context of the documentation:

Add Optic to your CI flow

Optic makes sure that every API change gets documented, reviewed and approved. breaking changes and problematic designs get flagged early, when they can still be fixed.

When optic run is called from a CI pipeline it:

• Optic diffs your local versions against the target branch for PR/MR events
• Optic exits 1 when it detects issues: this prevents you from shipping breaking or unwanted changes
• Optic posts a summary comment to your PR/MR containing links to relevant human readable reports

Check the docs on how to setup CI in a few simple steps.

Set your own API Standards

By default optic run only looks for breaking changes but there is much more it can do. Check how to set your own API governance rules.

API Contract testing

Development moves faster when the docs are accurate. Optic helps you keep your docs stay up-to-date by comparing them to your test traffic. When new endpoints are detected, Optic automatically updates your OpenAPI. Learn how to set up API contract testing here..

Need help?

We built Optic to help developers like us ship better APIs. Optic keeps your OpenAPI docs accurate, prevents breaking changes and makes sure every API changes is backwards compatible. Running Optic in CI helps teams ship better without slowing them down.

Get in touch with us :)