Alidade

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-19, against version 4.4.0 (development).

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.

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.

Making the second half work needs a different kind of page, which is on the plan as part of the cross-space API catalogue.

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 is full fidelity. Word and email export are not.

PDF renders the live page, so a PDF looks like the page. Word, email and page history use a different Confluence pipeline that cannot run the renderer, so they receive a generated endpoint table instead — accurate, but plainer.

We do not promise Word export. It is a different pipeline with a history of ignoring macro-generated content, and we would rather say so than have you find out on a deadline.

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. On a three-macro page we measured 12–13 seconds. 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.

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.

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

A specification added to a page that has never been published is not indexed until you save it again. The page renders correctly and the specification is stored — only the searchable list is missing, so the API will not appear in search or in the API catalog. The cause is Confluence rather than a choice of ours: until a page is published for the first time it has no content record to attach the index to, and the write is refused. If you added the macro while creating a brand-new page, publish the page, then open the macro's configuration, change the specification and save. Editing a specification on an already-published page is not affected.

If a field has the wrong type, the page and the index can disagree. The specification is read twice — once by the viewer that draws the page, once by us to build the searchable list — and the two are not equally forgiving.

Two cases we have measured:

Both documents are accepted and neither reading is wrong — the field simply is not the type the OpenAPI format specifies. Give these two fields their proper types and the page and the index agree.

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, which is not yet scheduled — it depends on the cross-instance catalogue being able to say which specifications are still in use.

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.