Skip to main content

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 and are run with the api scripts command.

What parameters are available when defining scripts?#

  • command: The command you wish to run to process a specification into your target product.
  • depends_on: a string or a list of strings, checks for the existence of the provided strings as commands. If they aren't present, the api scripts command will ask you to run again with the --install flag.
  • install: A command to manage the installation of any dependencies. This usually calls your local package manager, but it can be any command or shell script.

Define a script#

Scripts are defined in optic.yml and are given a name, like tasks. Scripts run the command you provide, and pass in the path to your project's OpenAPI file with the environment variables OPENAPI_JSON and OPENAPI_YAML. It also provides the environment variable SPECTACLE_URL for advanced queries against your current specification.

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.
  • provides environment variables to the script command
    • OPENAPI_JSON and OPENAPI_YAML - Contain the paths to the OAS files.
    • SPECTACLE_URL - Contains the URL to the running Spectacle server for advanced queries.
  • 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:

Start a script with a dependency
api scripts example-dependency
Output
[optic] Found Script example-dependencyChecking bin dependencies Requiring ["echo"]... ✓ All dependencies foundGenerating 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.yamlRunning 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:

Start a script without dependencies installed
api scripts example-brew-install
Output
[optic] Found Script example-brew-installChecking 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:

Start a script and install dependencies as necessary
api scripts example-brew-install --install
Output
[optic] Found Script example-brew-installChecking bin dependencies Requiring ["node","yarn"]... Missing dependencies[optic] Some bin dependencies are missing ["yarn"]. falseRunning install command: brew install node yarn ... ⣷Warning: node 14.9.0 is already installed and up-to-dateRunning install command: brew install node yarn ... ⣾Running install command: brew install node yarn ... ⣷Already downloaded: /Users/<user>/Library/Caches/Homebrew/downloads/b858a5ca4ade7c6Running 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.yamlRunning command:  echo "We'll call 'yarn --version' here" && yarn --versionWe'll call 'yarn --version' here1.22.5