To integrate with SwaggerHub, you'll need the following information:
- SwaggerHub API owner name such as
- SwaggerHub API project name such as
- SwaggerHub API version, such as
- 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
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: https://api.swaggerhub.com>? 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
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.