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.

name: Sample API
...
scripts:
publish-readme:
command: rdme swagger $OPENAPI_JSON --id=readmeId
depends_on: rdme
install: npm install rdme -g
mock-api:
command: prism mock $OPTICAPI_JSON
depends_on: prism
install: npm install prism -g

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 and OPENAPI_YAML. These contain the paths to the OAS files.
  • run the command

Running the publish-readme script defined above will look like:

api scripts publish-readme

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:

example-dependencies:
command: echo "This is a command with dependencies. The command might operate on $OPENAPI_JSON"
dependsOn: echo

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:

api scripts example-dependency
[optic] Found Script example-dependency
Checking bin dependencies Requiring ["echo"]... ✓ All dependencies found
Generating OAS file...
[optic] Generated OAS files
[optic] /Users/<user>/repos/example-ergast-project/.optic/generated/openapi.json
[optic] /Users/<user>/repos/example-ergast-project/.optic/generated/openapi.yaml
Running command: echo "This is a command with dependencies. The command might operate on $OPENAPI_JSON"
This is a command with dependencies. The command might operate on /Users/<user>/repos/example-ergast-project/.optic/generated/openapi.json

Multiple dependencies may be specified in a list:

example-brew-install:
command: echo "We'll call 'yarn --version' here" && yarn --version
dependsOn:
- node
- yarn

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:

example-brew-install:
command: echo "We'll call 'yarn --version' here" && yarn --version
dependsOn:
- node
- yarn
install: "brew install node yarn"

In an environment with brew and node installed, but not yarn, we'll see the following:

api scripts example-brew-install
[optic] Found Script example-brew-install
Checking bin dependencies Requiring ["node","yarn"]... Missing dependencies
[optic] Some bin dependencies are missing ["yarn"]. Run the command again with the flag '--install' to install them

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:

api scripts example-brew-install --install
[optic] Found Script example-brew-install
Checking bin dependencies Requiring ["node","yarn"]... Missing dependencies
[optic] Some bin dependencies are missing ["yarn"]. false
Running install command: brew install node yarn ... ⣷
Warning: node 14.9.0 is already installed and up-to-date
Running install command: brew install node yarn ... ⣾
Running install command: brew install node yarn ... ⣷
Already downloaded: /Users/<user>/Library/Caches/Homebrew/downloads/b858a5ca4ade7c6
Running install command: brew install node yarn ... ⣻
Running install command: brew install node yarn ... Success!
Generating OAS file...
[optic] Generated OAS files
[optic] /Users/<user>/repos/example-ergast-project/.optic/generated/openapi.json
[optic] /Users/<user>/repos/example-ergast-project/.optic/generated/openapi.yaml
Running command: echo "We'll call 'yarn --version' here" && yarn --version
We'll call 'yarn --version' here
1.22.5