Get started with Optic

Install Optic CLI

npm install -g @useoptic/optic

Run Optic

Try Optic in our demo Bookstore repo or in your own.

git clone git@github.com:opticdev/bookstore-example.git
cd bookstore-example
optic run

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

Uploaded API documentation is available from the APIs tabs in your https://app.useoptic.com (opens in a new tab) account:

Make a 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

Adding Optic to your CI flow will let you test and lint your OpenAPI files on every pull request. You can also configure Optic to post comments on your pull requests when OpenAPI files change:

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:

• Optic tests and lints your OpenAPI files according to your standards
• Optic diffs your local versions against the target branch and searches for breaking changes
• 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 :)