Get started with Optic

Install Optic CLI

npm install -g @useoptic/optic

Run Optic with our demo repo

git clone https://github.com/opticdev/bookstore-example.git
cd bookstore-example

Test if an OpenAPI file is accurate

Optic helps you keep your OpenAPI specification accurate. Your API tests are run through Optic's proxy. When existing endpoints have changed, Optic lets you know and makes it easy to patch the specification. When new endpoints are added, Optic helps you document them.

Run this command in the demo repo:

optic capture openapi.yml

This will run some tests and tell you about the API diffs it observed. It will exit 1 (like a snapshot test) because the spec is out of date.

Now run it again with the --update flag:

optic capture openapi.yml --update interactive

• The CLI will ask you if you want to document and start tracking the behavior of the new GET /author/{author_id} in your OpenAPI specification. Say yes.
• The CLI will patch the schemas to resolve the previous errors. Now your spec is up-to-date!

Test that API changes follow your style guide

Optic's diff command tests that API changes are backwards compatible, and that new and existing API endpoints follow your style guide. The style guide is configured in the optic.yml file.

Compute a diff:

optic diff openapi.yml --check --web

A visual API Changelog is generated and opened in your browser. It shows you exactly which endpoints were changed, and flags any design or compatibility issues:

Simulate a CI Run

Optic is designed to run in Pull Requests and give developers actionable feedback on their APIs changes before they merge. You can see what this looks like by running optic run locally. It finds all the OpenAPI specifications in your repository, checks that the specs are accurate, and then runs the breaking change + governance checks.

optic run

Does the above capture and diff test on every OpenAPI specification in the repo

You can learn more about running Optic in CI here

Tutorials

You can try Optic with your own APIs by following these tutorials:

1. Need to document an existing API? Generate OpenAPI from tests

2. Want to catch breaking API changes and improve your API design? Build an API Style Guide

3. Want to test if your API is working as designed? API Contract Testing

4. Want to improve the quality of your API reviews? Run Optic in CI

Need Help?