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 scriptScripts 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
install
parameter is supplied, the installation command is run. In this example,install
is 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_JSON
andOPENAPI_YAML
. These contain the paths to the OAS files. - run the
command
Running the publish-readme
script defined above will look like:
#
Set dependenciesOften 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 dependenciesThe 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: