Optic ensures that every API change your team makes is documented, reviewed and approved. Once you have an accurate API specification, you can imagine building automated workflows that publish that specification or generate API clients whenever it changes:
Optic Scripts can be configured in your
optic.yml file to serve all these use cases.
Scripts are defined in
optic.yml and are given a name, like tasks. Scripts run the
command you provide the most recent OpenAPI file.
A script is invoked by name with
api scripts <name>. Once invoked, it:
- [optional] checks for any defined dependencies in
- [optional] If defined dependencies are not present and an
installparameter is supplied, the installation command is run. In this example,
installis not defined as there are no dependencies defined.
- generates OAS files in both YAML and JSON format.
- provides environment variables to the script command:
OPENAPI_YAML. These contain the paths to the OAS files.
- run the
publish-readme script defined above will look like:
Often a script will depend on other installed packages to process the OAS file generated by Optic. Dependencies can be declared with
dependsOn as commands that should run successfully, and can be provided as a single command or a list of commands. The values supplied to dependsOn should be commands only, with no parameters or flags:
The command depends on
echo, and will print out the path to the OAS file in JSON format. In practice, this would be some command that operates on the OAS file to process it for another system or application. The results would look like:
Multiple dependencies may be specified in a list:
install parameter allows a command to be specified that will install the dependencies. It takes a single command which should be sufficient to install all dependencies. If your dependencies are complex, or require different dependency management systems, you may wish to call a script from
install to manage the process. Here's an example where we depend on
yarn, and will install them with Homebrew if they are not present:
In an environment with
node installed, but not
yarn, we'll see the following:
When we re-run it with the
--install flag, Optic will detect the missing dependency and invoke the
node is already installed, and Homebrew doesn't need to do anything there. It will install
yarn (which may include a lot more logging depending on the state of your system). Once the installation is complete, the
command runs just as before: