OpenAPI & Swagger Viewer documentation
Add API docs to a page
- Edit a page and type
/openapi. Choose OpenAPI & Swagger Viewer. - In the dialog, either paste the specification, or choose Use a file attached to this
page and pick a
.yaml,.ymlor.jsonfile. - The dialog shows the API title, version and number of paths. If the spec cannot be read, it says why before you save.
- 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 app | What moves |
|---|---|
| Open API (Swagger) Integration | Pasted specs |
| Visualize OpenAPI (Swagger) documentation | Pasted specs and attached files |
| Swagger UI for Confluence | Pasted specs |
| Open API (Swagger) Editor for Confluence | Pasted specs |
- As a Confluence admin, open Settings (the gear) and choose Move from old Swagger apps in the left menu.
- Click Find pages. Nothing is changed yet - you see every page and what will happen to each macro.
- 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.