Optic
APIs that Document & Test Themselves
How it Works • Key Features • Documentation • License
How it Works
Optic is like Git, but for your APIs
Add Optic to your Development Enviroment
Optic acts as a proxy, observing all API traffic during a session with your application. It's installed with the Yarn package manager, and initialized per API project you want to monitor.
Similar to
git init
Add the Optic Proxy so Optic can learn how your API works. It only takes 5 minutes and will save you hours if you write OpenAPI manually today.
yarn add global @useoptic/cli
# Navigate to your API project directory
api init
Then, add your start command to the optic.yml file created by api init. This allows Optic to start your project and observe its request traffic.
name: project
tasks:
start:
command: echo "your project start command goes here"
baseUrl: http://localhost:4000For further information, please check out our setup instructions.
Use the Optic Proxy to Monitor your API's Behavior
Once set up, you can start observing traffic with the api start command.
api start
[optic] Starting ToDo API on Port: 3005, with npm run server-startOptic will start your application, and observe API requests run against it. Optic manages these observations in a capture session. When Optic observes traffic that it hasn't yet seen, or that has changed from previous observations, it will list it with examples of payloads in the Optic Dashboard for the capture session. As you make changes to your code, such as adding or updating API endpoints, Optic will establish new capture sessions for each build and report back on observed behavior.
Our detailed setup instructions will get you started with additional context for several popular languages and frameworks.
Use Optic to Manage your API Specification
Optic organizes the API traffic it observes to allow you to manage expected behavior. It reports the shape of your payloads, or the types of data observed, for documentation. If the shapes change from what has been observed previously, Optic will report those changes. This helps identify that a change in behavior has been implemented properly, or catches unexpected behaviors before they get out into the wild.
Similar to
git diff,git addandgit commit
Optic constantly diffs your API's actual behavior against its specification. Optic shows you the API diff and makes it easy to:
- Add new API Endpoints to your specification
- Update the specification when it observes new behavior for an existing API Endpoint
- Catch bugs and unexpected API behavior early :)
As you committ the observed diffs, Optic builds documentation in OpenAPI format on the fly. You can see how your documentation looks, and how it changes, right in the Optic Dashboard as you work.
See it for Yourself
The best way to see Optic in action is to get set up in your current API project. You can also try our interactive demo to get a highlight of Optic's workflow and capabilities.
Key Features
It’s kind of like Git, but instead of tracking files, Optic automatically diffs and tracks API endpoints. When new behavior is observed, Optic makes it easy to update the spec.
Documentation https://useoptic.com/docs
- Read the full docs at: useoptic.com/docs.
- Want to contribute? Check out the Contribution Guidelines.
- To get set up working on the project, please review our Developer Setup guide as well.
License
MIT
Contributors ✨
Thanks goes to these wonderful people (emoji key):
 Aidan Cunniffe |
 devdoshi |
 Evan Mallory |
 Jaap van Hardeveld |
 Ronak Shah |
 taraedits |
 Lou Manglass |
 Nate Meyer |
 Tim Gates |
 Matthew Hudson |
 LaV |
 Gaurav Nelson |
This project follows the all-contributors specification. Contributions of any kind welcome!
