Optic Scripts
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.
Define a script#
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
dependsOn. - [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_JSONandOPENAPI_YAML. These contain the paths to the OAS files. - run the
command
Running the publish-readme script defined above will look like:
Set dependencies#
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 dependencies#
The 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 node and yarn, and will install them with Homebrew if they are not present:
In an environment with brew and 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 install command. 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: