How to add OpenAPI & Swagger documentation to Confluence Cloud

Updated October 2026 · 6 minute read

Confluence is where product managers, support engineers and partner teams look for information, so it's a natural home for API documentation. But Confluence Cloud has no built-in way to render an OpenAPI (Swagger) file. This guide walks through your options and the problems teams usually hit.

Option 1: Paste a link or a code block

The simplest approach is to link to your hosted docs (for example a Redoc or Swagger UI site) or paste the YAML into a code block. It costs nothing, but readers have to leave Confluence, code blocks aren't readable documentation, and both go stale as soon as the API changes.

Option 2: Embed hosted docs in an iframe

If your API docs are already hosted somewhere public, some teams embed them with an iframe macro. This only works for public docs, doesn't respect Confluence permissions, and many sites block being framed.

Option 3: Use an OpenAPI macro from the Atlassian Marketplace

Most teams use a Marketplace app that renders the specification with Swagger UI (or a similar viewer) directly on the page. When choosing one, check:

  • Where the spec can come from. Pasting YAML is fine for drafts, but for real APIs you want the macro to read the file your engineers maintain – from GitHub, GitLab, Bitbucket or a URL – so the page never drifts.
  • Private repositories. If your spec lives in a private repo, check how the app stores access tokens. Tokens should stay on the server side and be limited to the repositories an admin allows.
  • Whether “Try it out” works. Swagger UI's Try it out button sends requests from the reader's browser. Inside Confluence those requests are cross-origin and frequently fail with CORS errors – see the next section.
  • Forge vs Connect. Atlassian ends support for Connect apps on January 31, 2027. Prefer apps built on Forge, Atlassian's current platform, and check the “last updated” date on the listing.
  • Price. Marketplace apps are billed per Confluence user, so compare the per-user price at your site's size.

The most common problem: CORS errors

Two different requests can fail with “Failed to fetch” or a CORS message:

  1. Loading the specification from a URL in the browser. The server hosting the file has to send an Access-Control-Allow-Origin header allowing the app's origin. On Confluence Cloud you can't change Confluence, so you have to change the spec host – or use an app that fetches the spec on its server.
  2. Try it out requests to your API. Your API would need to allow cross-origin requests from the app's iframe origin, which most production APIs (rightly) don't.

Apps that fetch specs and relay Try it out requests from their backend avoid both problems. We wrote a separate guide on fixing Swagger CORS errors in Confluence.

Keeping docs in sync – and knowing what changed

Linking the macro to the spec in your repository keeps the reference current. The next question readers ask is what changed? Support and partner teams care less about the full reference than about the endpoint that was removed last week. Look for an app that keeps a version history and highlights breaking changes – removed endpoints, new required parameters, removed response fields.

How API Docket does it

We built API Docket to cover the points above: it reads specs from GitHub, GitLab, Bitbucket, a URL, an attachment or a paste; keeps private-repo tokens in Forge's encrypted secret storage, scoped by an admin; relays Try it out requests server-side so they don't hit CORS errors; and records a changelog that flags breaking changes on every update. It runs entirely on Atlassian Forge.

Whatever app you choose, start with one important API, link it to the spec in your repository, and add the page to your team's onboarding docs. That alone eliminates most “where are the API docs?” questions.