Skip to main content

Export your specification to SwaggerHub

What you'll need to know#

To integrate with SwaggerHub, you'll need the following information:

  • SwaggerHub API owner name such as api-owner
  • SwaggerHub API project name such as your-api-project.
  • SwaggerHub API version, such as 1.0.
  • SwaggerHub API key, for the swaggerhub-cli which we'll install later.

Preparing your SwaggerHub setup

Once you have an active project, there's no further setup required on your SwaggerHub account.

Integrating SwaggerHub with Optic scripts

Scripts are defined in your project's optic.yml file. We'll add a script definition to call the SwaggerHub CLI and update your documentation:

name: "todo-js" tasks:  start:    command: node server.js --port $PORT    inboundUrl: http://localhost:3001    scripts:  swaggerhub:    command: swaggerhub api:update <api-owner>/<your-api-project>/<version> --file $OPENAPI_JSON    dependsOn: swaggerhub    install: npm install --global swaggerhub-cli && swaggerhub configure

Running your Optic Script for the first time#

To ensure the dependency is installed, run:

api scripts swaggerhub --install

This will check for the SwaggerHub CLI swaggerhub, and if it isn't found, install it and configure it for your local use. Once installed, Optic will generate an up to date OpenAPI file and upload the latest specification.

[optic] Found Script swaggerhubChecking bin dependencies Requiring ["swaggerhub"]... Missing dependencies[optic] Some bin dependencies are missing ["swaggerhub"]. falseRunning install command: npm install --global swaggerhub-cli && swaggerhub configure ... โฃป
...? SwaggerHub URL: <default URL provided:>? API Key: <if previously configured, API key default suggested)Saved config to .../.config/swaggerhub-cli/config.json
Running command: swaggerhub api:update <api-owner>/<your-api-project>/<version> --file $OPENAPI_JSONUpdated API <api-owner>/<your-api-project>/<version>

This script runs swaggerhub configure on first install, so you'll only need to authenticate once. The SwaggerHub local CLI will store your key for future runs. You can run the configure command before the api:update command to be able to update your SwaggerHub URL or API key, though in practice you shouldn't need to do that often and only adds extra steps

Running your Optic Script generally#

You don't need to run your scripts command with the --install flag every time. Once installed, you can run:

api scripts swaggerhub

You will be prompted to log in, and your latest specification will be uploaded to SwaggerHub. SwaggerHub's CLI does allow you to set the configuration values (URL and API Key) as environment variables. This is handy if you want updates to run automatically such as in your CI pipeline on merges. Let us know if we can help you integrate your Optic Script further.