Optic is an open source project backed by YCombinator. It's great for documenting APIs and can output Swagger, API Clients or static documentation.
$ npm install @useoptic/cli -g
In order to learn your API spec, Optic needs to know:
How to run your API's integration tests
Which paths you want it to document
This configuration is defined in an optic.yml file placed in the root directory of your API repository. First navigate to your API repository:
$ cd path/to/repo
Then create an optic.yml manually or by running optic setup:init.
id: your-api-name # pick a slug for your API
version: 0.1.0 # a semantic version for the API
run_tests: npm run test # the command that runs your tests
paths: # the paths you want Optic to document
Optic will only document paths that are listed in the optic.yml. Since it might take a few minutes to fill out the paths section of the file, we suggest picking 3 paths to start and adding the remaining ones at the end of the tutorial.
Optic for Flask
Python APIs built on top of Flask are easy to connect to Optic using our custom middleware.
Add the Middleware to your Project
Install the Optic Documenting Middleware using pip
pip3 install optic-document-flask
Making the Middleware Run During Testing
Now add the middleware to your Flask App. Since we only want the middleware to run while Optic executes your tests, make sure you wrap it in a check for the OPTIC_SERVER_LISTENING environment variable.
We like performing this check within the block where we setup our test config, but you can do it anywhere that makes sense for your app.
from optic import OpticDocumentingMiddleware
if 'OPTIC_SERVER_LISTENING' in os.environ:
Before we continue, let's take a moment to make sure everything is set up properly. You can run optic setup:tests to verify that:
Optic's documenting middleware has been included correctly
the optic.yml is configured to run your API tests properly
$ optic setup:tests
Listening for API interactions in your tests... done
Observed >= 1 API Interactions. Your test setup is valid
All setup? Nice work! Let's document your API now.
Document the API
Now that you've added Optic to your API, you can run the document command anytime to get the current contract of the API and generate a Swagger specification.
$ optic api:document --generate oas
The OAS Spec will be generated in .optic/oas.
If this tutorial helped you check out Optic's Website and our GitHub to learn more about our other tools.