Last updated Apr 12, 2024

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.

From GitHub

  1. Make sure the GitHub link is publicly available, and ends in swagger.json, swagger.yml, or swagger.yaml.
  2. Find the Compass component you want to add the GitHub link to, and select Overview.
  3. Add the GitHub 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 GitHub link.
  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: