Last updated Apr 17, 2022

Rate this page:

Integrate Compass with Swagger UI

What is Swagger UI?

Swagger UI lets you visualize the OpenAPI (formerly known as Swagger) specifications of your Compass component, without having any implementation logic in place.

Integrate Compass with Swagger UI

You must first install the Swagger UI app on Compass. Then you can add a swagger.json file to your components to see the OpenAPI spec for those components.

Before you begin

Make sure you:

  • are an admin on your Compass instance
  • have access to your component's spec file

Set up the integration

  1. On Compass, select Apps from the top menu bar.
  2. On the Swagger UI tile, select Install.
  3. When the Swagger UI app is installed, select Configure.

Add a spec file to a Compass component

There are a few ways you can add a spec file to Compass components:

  • Using a webhook
  • From a link
  • From a local file

Using a webhook

This is useful if your spec file is part of your build process.

Here’s an example using the curl command:

1
2
curl -X POST -H "Content-Type: application/json" -d @my-swagger-file.json <webhook_url>
  • Replace my-swagger-file with your .json file's name.
  • Replace <webhook_url> with the URL on the code block on a component's Swagger UI page.

The spec file can be up to 5MB.

  1. Make sure the spec file link is publicly available, and ends in swagger.json, swagger.yml, or swagger.yml.
  2. Find the Compass component you want to add the spec file to, and select Overview.
  3. Add the spec file link to the Other links section.
  4. To view the spec, select the component’s Swagger UI page.

From a local file

  1. Find the Compass component you want to add the spec file to, and select Swagger UI.
  2. Select the From a local file tab.
  3. Drag the spec file onto the drop zone, or select the drop zone to find the file on your computer. The spec file can be up to 3MB.

Remove a spec file from a Compass component

There are two ways to remove a spec file from a Compass component, depending on how you added the spec file.

  1. Select a component’s Overview page.
  2. In the Other links section, find the spec file link that ends in swagger.json.
  3. Remove the link. This will remove the spec file from the component’s Swagger UI page.

If you added a spec file using a webhook or a local file

  1. Select a component’s Swagger UI page.
  2. Select Remove. The spec file will be removed from the component, and the page will refresh.

Uninstall the Swagger UI app

If you no longer have any need to use the Swagger UI app on your Compass instance, you can uninstall it.

  1. On Compass, select Apps from the top menu bar.
  2. On the Swagger UI tile, select Uninstall.

The Swagger UI app will be uninstalled, and Compass will no longer be integrated with Swagger UI.

If you uninstall the Swagger UI app before removing spec files

Spec files are cached for 15 days if you don't remove them from components before uninstalling the Swagger UI app.

This means if you uninstall and reinstall the app within a 15-day period, any spec files that weren't removed from a component before uninstalling the app will appear again.

Rate this page: