Documentation

API Docs for Confluence by Fernlight

On this page

Install
Add API docs to a page
Spec sources
Display options
Versions and breaking changes
Spec quality notes
Full screen, PDF and Word export
Publish from CI (GitHub Actions)
Supported formats
FAQ and troubleshooting

Install

A Confluence administrator installs the app from the Atlassian Marketplace: in Confluence go to Settings → Apps → Find new apps, search for API Docs for Confluence, and choose Try it free. No further setup is needed.

Add API docs to a page

Edit a page and type /OpenAPI (or /API docs), then choose OpenAPI / Swagger API Docs.
In the configuration panel, choose a spec source (see below). A live preview appears on the right.
Adjust the display options if you want to, then click Save and publish the page.

To change settings later, edit the page, select the macro and click the edit (pencil) icon.

Spec sources

Source	What happens
Page attachment	Pick any `.yaml`, `.yml` or `.json` file attached to the page.
Paste	Paste the spec text. It is saved as an attachment on the page, using the file name you give it.
Upload	Choose a file from your computer. It is attached to the page.

Specs always live as Confluence attachments. As a result they follow the page's permissions, get Confluence's version history, and are included in space exports and backups.

Display options

Option	Effect
Show tags	Only operations with the selected tags are shown. Leave all unticked to show everything.
Only paths matching	One pattern per line. `` matches one path segment and `` matches any number of segments, e.g. `/payments/*`.
Highlight changes since the previous version	Shows a change badge on the macro and on each changed operation (on by default).
Show models section	Lists the reusable schemas (`components.schemas` or `definitions`).
Hide deprecated operations	Removes operations marked `deprecated: true`.
Hide base URLs	Hides the server selector, e.g. for internal hosts.
Hide API description	Hides the top-level `info.description`.
Expand operations	All collapsed, first expanded, or all expanded when the page loads.

Readers can also filter operations by typing in the search box, and switch between servers when the spec defines more than one.

Versions and breaking changes

To publish a new version of the spec, upload a file with the same name to the page (Confluence adds it as a new attachment version), or paste into the macro again with the same file name. The macro always renders the latest version.

When the spec has more than one version, the macro compares the latest with the previous one. Click the change badge (for example 2 breaking changes) to open the What changed panel, where you can pick any two versions to compare.

Severity levels

Severity	Examples
Breaking	Operation or success response removed; parameter, request body or request property became required; new required parameter; type, format or pattern changed; request enum values removed; media type no longer accepted or returned; authentication added or an auth scheme removed; property removed from a response or no longer guaranteed.
Warning	New enum values in a response; new 2xx response; parameter, request body or error response removed; operationId changed; server removed.
Info	New operations, new optional parameters, newly deprecated operations and other additive changes. Hidden unless you tick Show non-breaking.

Spec quality notes

While a page is being edited, the macro shows a Spec quality button when it finds gaps. Examples: operations without a summary or operationId, no documented success response, undeclared path parameters, tags that aren't described, and a missing API description or servers list. Readers of the published page never see these notes.

Full screen, PDF and Word export

Use the ⤢ button to open large APIs in a full-screen view. When a page is exported to PDF or Word, the macro is replaced by a static table with the API title, version, and every method, path and summary.

Publish from CI (GitHub Actions)

Keep the page in sync with your repository using the free Publish OpenAPI to Confluence GitHub Action. On every push it uploads the spec as a new attachment version, so the macro updates and shows what changed. In pull requests it can fail the build when a change would break API consumers.

Create an Atlassian API token for an account that can edit the page, and store it as the repository secret CONFLUENCE_API_TOKEN. Store the account's email as CONFLUENCE_EMAIL.
Add a workflow step:

- uses: fernlightnz/publish-openapi-to-confluence@v1
  with:
    spec: openapi.yaml
    confluence-url: https://yourcompany.atlassian.net
    page-id: "123456"          # the number in the page URL
    email: ${{ secrets.CONFLUENCE_EMAIL }}
    api-token: ${{ secrets.CONFLUENCE_API_TOKEN }}
    mode: check                # or publish
    fail-on: breaking          # breaking | warning | none

Point the macro at the same attachment name (by default, the spec's file name). The API token lives only in your GitHub secrets. The Confluence app itself never sees or stores it.

Supported formats

OpenAPI 3.1.x, including webhooks and JSON Schema 2020-12 keywords such as type: [string, "null"].
OpenAPI 3.0.x.
Swagger 2.0.
JSON or YAML, with internal $ref references (#/components/…). References to external files or URLs are not resolved.

FAQ and troubleshooting

The macro says the license is not active

The app's subscription or trial for this site has ended. A Confluence administrator can renew it under Settings → Apps → Manage apps.

"Could not parse the spec as JSON or YAML"

Check that the file is valid YAML or JSON and has a top-level openapi or swagger field. The message includes the parser's description of the problem, which usually names the line.

Is there a "Try it out" button?

Not currently. Requests from a Confluence page to your API would usually be blocked by browser CORS rules and would need credentials entered in the page. The app provides copyable cURL, JavaScript and Python samples instead.

Who can see the spec?

Anyone who can view the page. The app reads attachments as the viewing user, so Confluence page and space restrictions apply.

Still stuck? Contact support.