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
On Compass, select Apps from the top menu bar.
On the Swagger UI tile, select Install.
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
Make sure the GitHub link is publicly available, and ends in swagger.json, swagger.yml, or swagger.yaml.
Find the Compass component you want to add the GitHub link to, and select Overview.
Add the GitHub link to the Other links section.
To view the spec, select the component’s Swagger UI page.
From a local file
Find the Compass component you want to add the spec file to, and select Swagger UI.
Select the From a local file tab.
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.
If you added a spec file from a GitHub link
Select a component’s Overview page.
In the Other links section, find the GitHub link.
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
Select a component’s Swagger UI page.
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.
On Compass, select Apps from the top menu bar.
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.