OpenAPI Swagger Viewer for Confluence

Quick start

This guide takes you from zero to a rendered API reference on a Confluence page in about five minutes. You need to be a Confluence site admin (to install) and have permission to edit the page you want to add the macro to.

1. Install the app

  1. In Confluence, open Apps > Find new apps (or go to the Atlassian Marketplace and search for "OpenAPI Swagger Viewer for Confluence").
  2. Open the listing and choose Try it free. Every site gets a 30-day trial, and sites with 10 users or fewer stay on the free tier.
  3. Confirm the install. The app is built on Atlassian Forge and Runs on Atlassian, so the install prompt does not ask for access to any external service.

2. Add the macro to a page

  1. Create a page or open an existing one and click Edit.
  2. Type /openapi in the editor and pick OpenAPI Viewer from the list. (You can also use the + toolbar button and search for it.)
  3. The macro appears as a placeholder with a configuration panel.

3. Paste your spec

  1. In the configuration panel, set Source to Paste.
  2. Paste your OpenAPI document. YAML and JSON are both accepted, and the versions supported are OpenAPI 2.0 (Swagger), 3.0.x, and 3.1.
  3. Click Save.

The editor shows a preview of the rendered spec. If the document cannot be parsed, you will see the parser message with a line number instead of a blank box. See Troubleshooting for how to read it.

Size limit: pasted specs are limited to roughly 150 KB because Confluence stores macro configuration with the page. If your spec is larger, use attachment mode instead. The macro tells you when you are over the limit.

4. Publish

Click Publish (or Update) on the page. Readers will now see the rendered API reference with:

  • Expand / collapse controls for operations and tags
  • Search within the spec
  • Deep links to individual operations, so you can share a URL that jumps straight to GET /pets/{id}
  • Full-screen view for long specs
  • Auto-height, so there is no inner scrollbar or cut-off content
  • Dark mode that follows the Confluence theme

What to do next

  • Specs change often. Rather than pasting a new copy each time, attach the file to the page and let the macro render the latest version.
  • Want the page to update automatically whenever your repository changes? Set up a CI push. This is also how you document specs that live in private repositories.
  • Coming from another Swagger macro? Read the migration overview.

What this app does not do

By design, version 1 does not fetch a spec from a URL and does not include "Try it out". Both would require sending data outside Atlassian, which would mean the app could no longer be Runs on Atlassian. The FAQ explains the reasoning and the recommended alternative.

Quick checklist

  • App installed from the Marketplace
  • Macro added to a page
  • Spec pasted (or attached) and saved
  • Page published
  • Rendered output checked in a normal (non-editor) page view

Need help?

See Troubleshooting or the FAQ. To report a bug, see "How do I report a bug or ask for help?" in the FAQ.