Get started with Optic
npm install -g @useoptic/optic
Try Optic in our demo Bookstore repo or in your own.
git clone firstname.lastname@example.org: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 to one of your OpenAPI specs. You could try a breaking change such as removing an endpoint or making an optional request parameter required.
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:
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.
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.
optic run only looks for breaking changes but there is much more it can do. Check how to set your own API governance rules.
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..
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.