OpenAPI & Swagger Viewer for Confluence

Overview

Show OpenAPI and Swagger API descriptions on Confluence pages as documentation the whole team can read: operations grouped by tag, with their parameters, request and response schemas, examples and a curl command.

• OpenAPI 3.0 and 3.1, and Swagger 2.0, in YAML or JSON.
• From a file attached to the page or from a code block inside the macro.
• Operations grouped by tag, with search by path, name or tag.
• Parameters, request body, responses and headers, with schemas that expand level by level.
• Example bodies generated from the schemas when the file has none, and a curl command for each operation.
• A Schemas tab with every model of the API.

Getting started

1. A Confluence administrator installs the app from its Atlassian Marketplace listing.
2. Attach the API description (.yaml, .yml or .json) to the page.
3. Edit the page, type /OpenAPI Viewer and insert the macro. With no settings, it shows the first attached file whose name looks like an API description.
4. Or paste the description inside the macro, in a code block, instead of attaching it.
5. Publish the page.

Macro settings

Where the description comes from, in order: the attachment named in the settings, the code block inside the macro, or the first .yaml, .yml or .json attachment of the page, preferring names with openapi, swagger or api.

Moving from another OpenAPI or Swagger app

Atlassian ends support for Connect, the platform used by Open API (Swagger) Integration, Visualize OpenAPI (Swagger) documentation, Swagger UI for Confluence and Open API (Swagger) Editor for Confluence, on 31 January 2027. This app is built on Forge and runs on Atlassian's cloud.

Existing macros of the other app are not converted automatically. For each page:

1. Make sure the API description (.yaml, .yml or .json) is attached to the page. If the old macro loaded it from a URL or a Git repository, download the file and attach it.
2. Type /OpenAPI Viewer and insert the macro. Name the file in Attachment if the page has more than one.
3. Delete the old macro and publish.

This app shows API descriptions; it does not edit them or call the API. Keep editing the file where you write your API, attach the new version when it changes, and use the curl command of each operation instead of "Try it out".

Both apps can be installed at the same time, so you can try this one before you uninstall the other.

Other app names on this page are trademarks of their owners. This app is independent and is not affiliated with them.

Limitations

• Files up to 4 MB.
• References to other files or URLs ($ref to another document) are not loaded; the page lists them.
• Descriptions from a URL and "Try it out" calls are not supported: copy the curl command to call the API.
• Webhooks (OpenAPI 3.1) are not shown.

Permissions

No egress: the app does not connect to any server outside Atlassian.

Data and privacy

The app stores nothing. The file is read with the permissions of the person viewing the page and parsed in their browser. Nothing is logged and no data leaves Atlassian. See the privacy policy.

Troubleshooting

The macro says this is not an OpenAPI description

The file needs an openapi: 3.x or swagger: '2.0' field at the top level.

Where exactly is the error?

For YAML or JSON that cannot be read, the message gives the line and column and shows the lines around it.

The app says it needs an active license

The app is paid and checks the license on every request. Ask your site administrator to check the app's subscription in the administration of Jira or Confluence (Apps → Manage apps). During a free trial the app works normally.

Need help?

See the support page.