You can install the Optic CLI directly from NPM.
This installs the Optic API CLI on your computer. The API CLI runs Optic locally so you can design, document and test the behavior of your API while you develop it locally.
Optic learns your API's specification by watching how it behaves while it is being developed and tested. If the observed behavior deviates from the published API specification, Optic will ask you if you want to 'merge' changes into your spec, or 'mark them as errors'.
This workflow makes it easy to keep your documentation up-to-date and it ensures that developers do not accidentally break the API's contract while they are building other features.
If you currently have an OpenAPI specification that describes your API, you can import it to Optic. It's probably not as accurate as you would hope, but Optic can quickly fix the inaccuracies.
Adding Optic to your API is easy.
Open your terminal of choice and change your working directory to your API's root directory. Then run api init and provide the following information:
Optic passes an environment variable into your API process called OPTIC_API_PORT. The port in the environment variable is where Optic will forward traffic from its proxy. You should configure your API to bind to that port while your API is running in development.
Every team has a different way of choosing which port to bind to in development vs. production so it's difficult to prescribe a set of common code changes. Here's pseudocode describing the changes you need to make and a concrete example from one of our Node APIs:
Having trouble? Contact us on Intercom (chat in the bottom right and we'll help you out
Optic documents your API as you develop it meaning your docs are accurate, and never out-of-date. All you have to do is start your API with our api start command and Optic does the rest.
Here's our write up on how the Continuous Documentation feature currently works.
The feature is in the final stages of Beta and will be released in the next few weeks. You can use api start to begin collecting data about your API's behavior and evolution, but you won't be able to use that data unless you join the Beta or wait for the general release. If you're interested in being part of the Beta visit this page and fill out the Typeform survey.
Optic ships with our beautiful, open source, visual API Designer and Docs Viewer. These tools run locally and only save data in your git repository.
Optic is great for all of your team's API consumers because it provides:
Optic is the most powerful API designer available today:
Optic makes it easy to generate server code, client SDKs, static documentation, tests, OpenAPI specs and much more.
What would you be interested in generating?
Thanks for your input! We'll do our best to build that generator soon!
Today we have full support for exporting OpenAPI specs from Optic.