Documentation for “Visualize OpenAPI (Swagger) definition” app for Confluence

Widget helps Confluence users to present API definitions in a nice visual and interactive way directly on the Confluence page. It leads to more efficient collaboration with colleagues and stakeholders, simplifies API verifications and further API development. Design, describe, and document your API with built-in Swagger Editor. Valid Swagger JSON descriptions can then be generated and used with the full Swagger tooling (code generation, documentation, etc).

Thousands customers are already using it. Try it now for free and enjoy the functionality. Visualize OpenAPI (Swagger) documentation on Atlassian Marketplace. Try the live demo.

No extra actions are needed to update from version 1.0.13-AC to latest 1.1.0-AC. More details at Upgrade details page.

Getting started

Edit confluence page and type /OpenApi or open ‘Insert’ -> ‘View More’ dialog and select ‘OpenAPI (Swagger) visualization’.

Insert widget directly on page with ‘/’
…or select it from ‘Select macro’ popup

Paste definition to the text area and click ‘Insert’. API definition need to follow OpenAPI specification (version up to 3.0.3 supported) and can be created using YAML or JSON.

Place API definition (YAML or JSON) to text area

After page is published the definition nicely appears on the page.

Saving specification as attachment

Pages in Confluence can have file attachments. “Visualize OpenAPI (Swagger) definition” widget can store and use API definition stored as page attachment. It gives possibility to download it as file as well as see modification history. Removing widget from page keeps the definition still available.

To save the API definition as attachment check the “Store API definition as attachment” checkbox and enter filename

Check the checkbox to store as attachment

It will result in the file created in the page’s attachment section. Each time the specification is changed the new version of the file is created. It is visible who and when edited the definition.

Using remote API definition

It is possible to configure widget to load API definition from remote location. To do so switch to ‘Remote location’ tab and enter the URL to the ‘API definition URL’ field. The definition is requested every time the widget is about to display. Every time it shows latest version of the remote file. User should not update widget if remote definition has changed.

In case definition is protected by username/password (basic authentication) or is hosted in private Github repository the corresponding fields need to be filled in in the form.

Read detailed instructions on remote repositories support.

Display options

Various options specify how visualized specification will look like.

Expand: Controls the default expansion setting for the operations and tags. It can be ‘Tags only’ (expands only the tags, default), ‘Tags and operations’ (expands the tags and operations) or ‘Nothing’ (expands nothing).

Tag list order: It can be ‘By paths alphanumerically’ or ‘Default’ (the order determined by Swagger UI).

Operations order: Apply a sort to the operation list of each API. It can be ‘By paths alphanumerically’’, ‘By HTTP method’ or ‘Default’ is the order returned by the server unchanged.

Enabled HTTP methods: List of HTTP methods that have the “Try it out” feature enabled. When nothing is selected the “Try it out” is disabled for all operations. This does not filter the operations from the display.

Online validator URL: By default, Swagger UI attempts to validate specs against swagger.io’s online validator. You can use this parameter to set a different validator URL, for example for locally deployed validators (Validator Badge). Setting it to either none, 127.0.0.1 or localhost will disable validation.

Swagger Editor

After Visualize OpenAPI (Swagger) documentation app is installed the link to Swagger Editor appears in the drop down menu that is shown when user clicks on icon.

Clicking on the ‘Swagger Editor’ link brings you to the editor page. It allows you to import, design, edit and export OpenAPI definitions in YAML or JSON format. Swagger Editor provides ability to generate Server and Client side code for various languages and frameworks.

Please note: when using generate functionality the specification is sent to a third-party service https://generator.swagger.io/. We do not control this service and are not responsible for the potential security risks related to its usage.

Useful links

Engineering Manager / Agile Coach