Review APIs with Confluence
The API Hub for Design Integration for Confluence macro allows you to embed an API definition into a Confluence page (cloud Atlassian only).
How to get the macro in your Confluence installation
To install the macro, go to Atlassian Marketplace. Download the plugin and install it.
How to embed an API into a Confluence page
To insert the API Hub for Design Integration for Confluence macro into a page, click on the + (insert) command in Confluence and type "swagger" into the Search box. Click on the API Hub for Design Integration for Confluence in the list and the macro will be inserted.
The macro dialog behaves like other Confluence macros. Simply fill in the values and click the Insert button to insert an API definition.
Specify the type of API definition: OpenAPI or AsyncAPI.
Enter the API to be embedded. You can do this two ways:
Import the API definition into Confluence by pasting the API file into the API Definition field at the top right of the dialog OR dragging and dropping a file into the Upload area at the right – If you import in this way, you must re-import the API when you make changes.
Enter a URL in the API > URL field in the left column – if you link a URL in this way, changes to the API will be re-loaded into your Confluence page whenever a user reloads the page.
Specify the Access Token/API Key or access credentials for the API (if required).
How to get an API token
For protected APIs that you have access to, you can get an API key from API Hub for Design and use it to access protected API definitions. To retrieve an API key, go to Settings > API Keys in API Hub for Design. You can then generate an API key which can be entered in the API Key field.
How to reference a API Hub for Design API definition by its URL
Your API Hub for Design API definitions can be accessed through this pattern:
https://api.swaggerhub.com/apis/{owner}/{api}/{version}
If you are using API Hub for Design on-premise, your API Hub for Design API definitions can be accessed through this pattern:
http(s)://SERVER/v1/apis/{owner}/{api}/{version}
If your on-premise installation of API Hub for Design is airgapped or behind a firewall, you may need to contact tech support to figure out how to embed your APIs using this Confluence macro.
Specifying OpenAPI options
For OpenAPI files you will have the following options.
Specifying AsyncAPI options
For AsyncAPI files you will have the following options.
Embedding the API into the page
Once you have specified the desired options, click on Insert to embed the API definition into your Confluence page.
Working with embedded APIs
Once your API is embedded, the controls are simple and standard. Use the v control to expand items and the ^ control to collapse items.
