# Modern OpenAPI (Swagger) Integration for Confluence — User Guide

## Overview[​](#overview "Direct link to 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[​](#requirements "Direct link to 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[​](#installation "Direct link to 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[​](#how-to-find-the-app "Direct link to 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[​](#using-the-app "Direct link to Using the App")

### Configuring the macro[​](#configuring-the-macro "Direct link to 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[​](#viewer-options "Direct link to Viewer options")

These settings control how the API documentation appears to readers.

| Setting    | Description                                                   | Options                                                                        | Default |
| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------- |
| Expansion  | How much of the documentation is expanded when the page loads | Tags (collapse to tag groups), All (expand everything), None (fully collapsed) | Tags    |
| Models     | How data models (schemas) are displayed by default            | Example (shows sample values), Schema (shows the type structure)               | Example |
| Tag filter | Shows a search box that filters API operations by tag name    | On or Off                                                                      | Off     |

info

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

### Viewing the documentation[​](#viewing-the-documentation "Direct link to 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[​](#tips--common-workflows "Direct link to 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[​](#troubleshooting "Direct link to 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.

Was this helpful?👍 Yes👎 No