Skip to main content

Modern OpenAPI (Swagger) Integration for Confluence — User Guide

Overview​

Modern OpenAPI (Swagger) Integration for Confluence is a Confluence app that renders interactive API documentation directly on your pages. Paste an OpenAPI 3.x or Swagger 2.x specification in YAML or JSON format, and the app displays a polished, navigable view of your API endpoints, parameters, request/response examples, and data models — all inside Confluence.

Requirements​

  • Confluence Cloud
  • Any Confluence user can insert and configure the macro on a page
  • A site admin must install the app from the Atlassian Marketplace

Installation​

  1. Go to Settings → Manage apps (site admin required).
  2. Click Find new apps and search for Modern OpenAPI (Swagger) Integration for Confluence.
  3. Click Install.
  4. Once installed, the macro is available to all users on the site.

How to Find the App​

The app appears as a macro in the Confluence editor.

  1. Edit any Confluence page.
  2. Type / or click the + (Insert) menu.
  3. Search for Modern OpenAPI (Swagger) Integration for Confluence.
  4. Select it to insert the macro.

Using the App​

Configuring the macro​

When you insert or edit the macro, a full-screen configuration panel opens with a code editor on the left and controls in the top bar.

  1. Paste your spec — Paste an OpenAPI 3.x or Swagger 2.x spec in YAML or JSON format into the editor.
  2. Format — Click the Format button to auto-format and indent your spec.
  3. Validation — The spec is validated automatically as you type. A green badge confirms it is valid; a red badge shows the error.
  4. Set viewer options — Configure how the documentation displays (see table below).
  5. Click Save to publish.

Viewer options​

These settings control how the API documentation appears to readers.

SettingDescriptionOptionsDefault
ExpansionHow much of the documentation is expanded when the page loadsTags (collapse to tag groups), All (expand everything), None (fully collapsed)Tags
ModelsHow data models (schemas) are displayed by defaultExample (shows sample values), Schema (shows the type structure)Example
Tag filterShows a search box that filters API operations by tag nameOn or OffOff
info

The Tag filter searches by tag name (e.g., "pet", "store", "user") — it does not search endpoint paths or descriptions.

Viewing the documentation​

After saving, the macro renders a full interactive API documentation view on the Confluence page. Readers can:

  • Expand and collapse sections to browse endpoints
  • View request and response examples for each operation
  • Explore data models and switch between example and schema views
  • Use the tag filter (if enabled) to quickly find operations by tag

The viewer automatically matches your Confluence theme — light or dark mode.

Tips & Common Workflows​

  • Start with a small spec — Paste a minimal OpenAPI spec first to verify it works, then expand with more endpoints.
  • Use YAML for readability — YAML specs are easier to read and edit in the code editor. JSON is also fully supported.
  • Tag your operations — Use meaningful tags in your spec so the tag filter becomes useful for navigating large APIs.
  • Set Expansion to "None" for very large specs — This keeps the page tidy and lets readers open only the sections they need.

Troubleshooting​

Symptom: Macro shows "No spec configured" : The macro was inserted but no spec was saved. Edit the macro and paste your OpenAPI spec.

Symptom: Red badge says "Invalid spec" : The pasted content is not valid YAML or JSON, or does not follow the OpenAPI/Swagger format. Check for indentation errors in YAML or missing brackets in JSON.

Symptom: Macro shows "Failed to load spec" : The stored spec may be corrupted. Edit the macro, clear the editor, and paste the spec again.

Symptom: Tag filter returns no results : The filter matches tag names only (case-sensitive). Check that the text you type matches a tag name defined in your spec's tags section.

Symptom: Spec is too large to save : The maximum spec size is 1024 KB raw. Consider splitting a large spec into smaller, focused documents.