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’.
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.
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
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 access to the URL will be automatically checked after you update URL, username, password or token.
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 remote repository the corresponding fields need to be filled in in the form.
App supports multiple GIT repository providers such as Github, Microsoft Azure DevOps, Gitlab, Bitbucket and others.
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.
