OpenAPI & Swagger Viewer documentation

Last updated 1 October 2026

Add API docs to a page

  1. Edit a page and type /openapi. Choose OpenAPI & Swagger Viewer.
  2. In the dialog, either paste the specification, or choose Use a file attached to this page and pick a .yaml, .yml or .json file.
  3. The dialog shows the API title, version and number of paths. If the spec cannot be read, it says why before you save.
  4. Save and publish the page.

Supported: OpenAPI 3.0 and 3.1, Swagger 2.0, YAML or JSON.

Keeping docs current

With an attached file, upload a new version of the same file name and the page shows it the next time it loads. With a pasted spec, edit the macro and paste the new version.

Why "Try it out" is off

Sending test requests from Confluence would mean the app reaching your API from Atlassian's platform. The app is built to make no outside requests at all, so it documents the API without calling it.

Migrating from the retired Swagger apps

These apps were built on Atlassian Connect, which reaches end of support at the end of 2026. Their macros keep working only until platform changes break them.

Old appWhat moves
Open API (Swagger) IntegrationPasted specs
Visualize OpenAPI (Swagger) documentationPasted specs and attached files
Swagger UI for ConfluencePasted specs
Open API (Swagger) Editor for ConfluencePasted specs
  1. As a Confluence admin, open Settings (the gear) and choose Move from old Swagger apps in the left menu.
  2. Click Find pages. Nothing is changed yet - you see every page and what will happen to each macro.
  3. Click Migrate all. Each page gets a new version with the old macros replaced.

Every change is a normal page version, so any page can be restored from its history. Only pages you are allowed to edit are changed.

Macros that loaded the spec from a URL

These are left in place and listed with their URL. Open the URL, save the file, attach it to the page, then insert this app's macro and choose the attachment.