Limitations

What this app does not do, and why.

This page exists because of one measured fact about this category: across ~120 reviews and 13 community threads, every bad review is a surprise a page like this would have prevented. Only 4 of 12 vendors publish one. So the rule for this file is: a limit goes in here the day it is found, in the words a customer would use, whether or not it makes us look good.

Nothing here is a roadmap. If something is planned, it says so; if something will never work, it says that instead.

Last updated 2026-08-22, against version 6.6.0 (development).

Where a specification can come from

There are four ways to get a specification into a macro, and each has an edge.

Pasting stores exactly what you pasted, up to 4 MB. Replacing it stores a new copy; the old one is not deleted (see Storage).

A public URL is fetched once, in your browser, when you save. The page never fetches it again on its own: readers see the copy that was stored, and an editor re-opens the configuration and presses Refresh to update it. This is deliberate — a page that re-fetched on every view would make every reader's browser call your host, and would show the URL to every reader. The URL itself is never written to the page and is shown only to people who can edit it; a URL carrying a token in its query string is stored in encrypted storage like any other secret. It must be reachable from the editor's browser and must allow cross-origin requests from this app's frame — the same rule as Try it out above. GitHub, GitLab and most documentation hosts do; an internal server behind a VPN or without CORS headers does not, and the error message names the origin to allow. If the host cannot be changed, paste the document or push it from CI.

A page attachment is read once, when you save. Uploading a new version of the attachment does not update the macro; re-open the configuration and load it again. If you want the page to follow a file that changes, use the CI push. The attachment has to be on the same page as the macro.

CI push. Your pipeline sends the specification to an address this app gives you, with a token it also gives you. Things to know:

• The token is shown once, when it is created or rotated. It is not stored anywhere we can read it back from — only a hash is — so a lost token is replaced, not recovered.
• The push is accepted or refused with a status code only: 200, 400, 401, 404, 413 or 422. The address cannot answer with details, by design of the platform feature it uses. When a push is refused because the document is not valid, the reason is shown in the macro configuration, not in your CI log.
• A push replaces the content immediately and without review. Validate the document in the pipeline before sending it.
• Copying the page copies the macro, and the copy keeps following the same pushes — the address identifies the specification, not the page. To give the copy its own feed, create a new push endpoint in its configuration.
• If someone saves the configuration with a pasted or fetched document while the pipeline is also pushing, whichever finished last is what readers see.
• The push address is one per Confluence site. It does not change when this app is updated.
• A push that arrives while the page is still an unpublished draft is stored and rendered, but its search index is not written -- Confluence does not accept properties on a draft. The next push after publishing indexes normally.

Storage that is not reclaimed. Three things leave data behind, knowingly: a save that is interrupted after the upload began leaves the partial copy; every CI push keeps the previous copy it replaced; and every replaced document (see Storage below) keeps the old one. Deleting any of it safely needs a sweep that can see every page. The API catalogue can now say which specifications are still in use, which was the missing piece — but the sweep itself is not built, and not scheduled. None of this affects what readers see. It costs storage, which is inexpensive, not correctness.

Try it out

Your API must allow cross-origin requests, or "Try it out" cannot reach it. The request is sent from the reader's own browser, from inside this app's frame — not from Atlassian's servers and not from your Confluence site. Your API has to return an Access-Control-Allow-Origin header covering that frame's origin, and answer the browser's OPTIONS preflight.

The app tells you the exact origin to allow when a request fails, because only the running frame knows it. It is an *.cdn.prod.atlassian-dev.net address, and it stays the same across app updates, so it is safe to add to an allow-list.

No app can send those headers for you. Any vendor implying otherwise is describing a proxy that reads your traffic.

An API reachable only from inside your network cannot be called at all. Not by us, not by any competitor: the request leaves from wherever the reader is sitting. A VPN-only or firewalled API will always fail here.

Try it out is ON by default. Turn it off per macro in the configuration panel if you do not want readers issuing requests.

OAuth2 redirect flows do not work. Atlassian's app frame is not allowed to open popups, so Swagger UI's OAuth2 authorisation popup cannot open. API keys, bearer tokens and basic auth all work normally. We do not show an OAuth button that would silently do nothing.

Links to a single operation

You can copy a link to any operation. Following that link lands the reader on the right page, but does not open or scroll to the operation.

This is a platform limit, not an oversight, and it is worth stating precisely because no competitor offers even the copy half. A macro on a Confluence page cannot see the page's own URL — not the query string, not the fragment — and every macro on a page is served the identical frame address. So nothing in a link can tell the macro which operation was meant. We measured this rather than assumed it.

The link still carries the operation name, so a person reading it in Slack or a Jira ticket can see what it points at.

The API catalogue does not change this. It will take you to the page that documents an API, which is the useful half, but it cannot open the operation for you: the macro on that page still has no way to read the link that brought you there. Until the platform lets a macro see its own page's address, the second half is not buildable — by us or by anyone.

What the display settings do and do not do

Hiding tags or paths is a display filter. It is not access control.

The specification you upload is stored whole, and anyone who can read the Confluence page can retrieve it whole. Restricting a macro to certain tags or paths changes what is drawn; it does not make the rest secret. Schemas that only hidden operations referenced are dropped from the rendering too, which keeps the page tidy — but that is still tidiness, not security.

If a specification contains something a reader must not see, remove it from the specification before uploading it.

Hiding the title also hides the version badge. They live in the same heading, and a version stamp floating alone with no title reads as a bug.

References to other documents

A $ref pointing at another file or a URL is never fetched. The operation or schema behind it renders as a note naming the reference that was not followed.

This is deliberate. A specification is rendered for everyone who can see the page, so a link inside one would make every reader's browser call that address, automatically, with no click. That is not a thing this app will do on your readers' behalf.

Paste the complete document, with its references resolved. Most toolchains can bundle a multi-file specification into one; redocly bundle and swagger-cli bundle both do it. Internal references — anything starting with #/ — work normally and are the common case.

Size

A specification must be under 4 MB. Above that it is refused at upload with a message naming the limit.

The ceiling comes from the platform: the app reads the document back in one response, and Atlassian caps that at 5 MB. 4 MB leaves room for the encoding overhead. A 4 MB OpenAPI document is roughly 1,700 operations, which is far larger than any API we have seen documented on one page.

Very large specifications are slow to save, because the document is uploaded in pieces. Rendering is fast once saved.

Export

PDF export works. Word export does not carry this macro at all.

PDF renders the live page, so a PDF looks like the page.

Word export contains none of this macro's content — not the documentation, not a table, not even an error. We measured this on a deployed four-macro page on 2026-08-22: the exported .doc was 6,204 bytes and byte-identical whichever Export setting the macros carried, and held the page title and nothing else. This is Confluence's own Word pipeline and there is nothing the macro can do about it. If you need the API documentation in Word, export to PDF instead, or copy the endpoint table out of the PDF.

We have not measured email or page history. They use the same pipeline, so do not assume they carry the table either until this page says they do.

You can ask for the table in PDF too. Each macro's configuration has an Export setting: Show the API as it appears on the page (the default) or Show a table of endpoints. It changes the PDF and nothing else.

How much it saves depends entirely on how large your specifications are. Two measurements, both on real pages:

The pattern worth knowing: the full render grows with your specification, the table barely does. On a big API the full-render PDF was thirteen times the size and three and a half times slower. If your PDF is for reading rather than archiving, the table is the better default at that size.

An inline macro inside a Confluence table currently fails to export to Word. Use a block macro.

Exporting a page with many macros is slow. Each macro instance is exported separately, and Atlassian's own documentation notes this can hit their invocation rate limits. See the table above for what we measured. We have not measured 10+ instances, and neither has Atlassian published a ceiling.

The export honours your display settings. If a macro is limited to one tag, the exported table is limited to that tag too.

How many macros on one page

Plan for about 20–30 on a single page. Each macro is a separate frame, and browsers limit how many connections a page can open at once. Confluence itself stops rendering a page after 30 seconds. Pages with 50–200 macros have been reported to stall.

Three on one page is measured and fine.

Search

The rendered output is not searchable. Confluence does not index what an app draws inside its frame — this is true of every app of this kind, ours included.

What is searchable is published separately: the API title, its version and its endpoint list. That index is capped at 32 KB per page by Confluence, so on a very large specification the endpoint list is truncated rather than dropped.

That index answers CQL, and it does NOT answer the ordinary search box. Typing an operation id into the Confluence search field at the top of the page finds nothing. Measured 2026-08-27: openapi_operations ~ "listStorageLocations" returns the right page, and the same word typed into the search box returns "We couldn't find any matches" — in the quick dropdown and on the full search page alike.

This is how Confluence content properties work rather than a choice of ours: the index lives in named fields, not in the page text the search box reads. So there are three places an endpoint search works, and one where it does not:

• The API catalogue's Find by endpoint tab — the one built for this, and the one to point people at.
• CQL, in the advanced search, in the CQL query builder (the fields appear as API title, API operations, API paths, API tags), and in the Page Properties Report macro.
• The REST search API, for anything scripted.
• Not the plain search box.

Confluence's search index updates asynchronously, so a newly saved specification can take a few minutes to become findable.

The API catalogue

The catalogue lists every API specification published on your site, one row each — title, version, number of endpoints, space, a link to the page, and when it was last saved. Open it from the Apps menu in the Confluence header, as API catalogue. You can filter the list as you type, sort it by any column, or switch to Find by endpoint and look for an operation, a path segment or a tag.

It lists only what you can see. It is not an audit of your site. The catalogue searches as you: a page you are not allowed to open never appears in it, and a colleague with wider access will see more rows than you do on the same site. Read it as "the APIs I can find", never as "the APIs that exist".

A specification appears in it a few minutes after its page is saved, for the reason given under Search above — Confluence's index catches up in the background, and the catalogue can only list what that index already knows.

A specification published by an older version of this app is listed without its details. Its row carries the API title and version but a dash where the endpoint count and the date would be, and it only turns up through Find by endpoint, never in the browse list. Open its page, save the macro once more, and it is listed in full from then on.

Very large sites are listed up to a limit. The catalogue reads the first 500 pages that publish a specification, and says on screen when there are more than that. To reach the rest, narrow what you are asking for: a search for a particular endpoint returns far fewer pages than browsing everything, so the limit stops biting.

Searching by endpoint matches whole words. Look for petId, not /pets/{petId} — the punctuation in a path is a word separator, so the punctuated form finds nothing. Several words are combined with and: each one has to appear somewhere in that page's endpoints, paths or tags. The exact rules, with worked examples, are in Finding an API in Confluence search (docs/SEARCH.md).

The catalogue takes a few seconds to open, because it runs a fresh search every time rather than keeping a stored copy of your site. On a test site with three specifications we measured under 7 seconds from click to table.

Migrating from another app

The Migrate tab of the API catalogue finds API specification macros belonging to other Confluence apps and replaces them with ours, keeping the specification. It always shows you what it will change before it changes anything, and it can put every page back.

Some apps store a username, password or access token inside the page. We never read those values and never carry them across. Replacing the macro removes them from the current version of the page — but not from the page's history, which anyone who can view history can still read. The migration lists every page where it found one so you can rotate the credential. This is not something any app can fix for you; it is a consequence of where the other app chose to put it.

Macros inside synced blocks are invisible. A synced block's content is not part of the page, so nothing that reads a page body can see into one — the migration included. A page we report as having no macros left may still contain one inside a synced block. Check those by hand before you uninstall the other app.

Macros placed inside a line of text, or with content of their own, are listed but never changed. Confluence's document format does not allow swapping a block macro into the middle of a sentence, and replacing a macro that has a body would delete that body. Those need a person.

Apps are recognised by their configuration, not by a signature. Confluence attaches no vendor identity to this kind of macro, so recognition is based on the macro's key and the settings it carries. Review the list before applying it. Where two apps share a key and cannot be told apart, we list neither rather than guess.

Some apps we can find but not yet read. We recognise the macros of every major app in this category, but reading a specification out of one requires knowing that app's setting names, which we confirm against a real installation rather than guess — guessing would let us replace a macro with the wrong content. Macros from an app we have not confirmed are listed as found and left exactly as they are.

One app in this category cannot be migrated at all. Warsaw Dynamics' Macro Pack renders several formats — Swagger, Mermaid, PlantUML and more — and the page does not record which one a given macro is. Changing it could replace a diagram. We list those macros and never touch them.

A macro pointing at a URL is not migrated yet, only one holding the specification itself. It is listed and left alone.

Only pages you can both see and edit will change. Confluence's search only returns pages you can read, and that is not the same set as the pages you can change — so the scan asks about each page it would otherwise offer, and one you cannot edit is listed as skipped rather than attempted. Nothing is silently dropped.

A page someone else saves during the run is skipped, not overwritten. We re-read every page immediately before writing it and refuse it if it moved, because writing what we read minutes earlier would silently discard their edit. Scan again to pick it up.

Undo is offered while the catalogue page stays open, and refuses a page that has been edited since the migration — undoing then would throw those edits away. Every change is also an ordinary page version, so Confluence's own page history can restore any of them at any time, with or without this app.

A very large scan stops at 500 pages. Narrow it to one space to see the rest.

A page can fail on its own, and the run carries on without it. Measured on 2026-08-22: in a twenty-page run, one page came back 500 from Confluence with no cause given. The other nineteen migrated, that page was reported as could not be saved and left exactly as it was, and nothing was half-written. Re-running the same page minutes later succeeded, unchanged — so it was Confluence having a moment, not anything about the page. There is no automatic retry: scan again and migrate the pages that were left.

Storage

Replacing a specification leaves the old one stored. It is not deleted, deliberately: copying a macro or duplicating a page copies the pointer too, so two macros can share one specification, and deleting on replace would empty someone else's page. Reclaiming that space needs a sweep that can see every page. The API catalogue can now say which specifications are still in use, which was the missing piece — but the sweep itself is not built, and not scheduled.

This costs storage, not correctness, and Forge storage is inexpensive.

Accessibility

Method badges do not meet WCAG AA contrast in light mode. GET, POST, PUT, PATCH and DELETE are white text on Swagger UI's brand colours, which measure between 1.6:1 and 3.6:1 against a 4.5:1 requirement. This is inherited from Swagger UI and is the same in every app built on it.

Dark mode is fixed. In dark mode those same badges use dark text and measure 7.4:1 or better, and we have separately corrected the places Swagger UI's own dark theme leaves unreadable — most visibly deprecated operations, which were effectively invisible at 1.19:1 and now measure 10.96:1.

If light-mode contrast matters to you, Confluence's dark mode is the accessible path today.

Runs on Atlassian

This app does not carry the Runs on Atlassian badge, by choice.

The badge requires that an app make no outbound network requests of any kind. "Try it out" is an outbound request from the reader's browser, and so is fetching a specification from a public URL. We judged those two features worth more to you than the badge.

What that does not mean: the app still runs entirely on Atlassian's infrastructure, your specification is still stored inside your Atlassian site, and nothing is sent to us or to any third party. The only outbound requests are the ones you ask for, to the addresses you name.

We never store a credential of any kind — no repository tokens, no API keys. There is no field to enter one, on purpose.