Moving from another OpenAPI app
Most Confluence sites that need this already have a Swagger or OpenAPI macro on dozens of pages. Redoing that by hand is the real cost of switching — roughly 15–30 hours for 300 pages — and it is why people stay on an app they have stopped liking.
Our app can do part of that for you, in one action. This page is about which part, because the honest answer is not "all of it".
How it works
Another vendor's macro stores its configuration in the Confluence page itself, not in that vendor's private storage. That is what makes a migration possible at all: the specification is already sitting in the page body, and reading it needs no cooperation from the app that put it there.
- Scan a space. One search finds only the pages that actually carry another vendor's API macro. Pages without one are never opened.
- Read the dry run. You get a list: which page, which vendor's macro, what would happen to it, and any warning worth reading first. The dry run writes nothing. The preview and the real thing are the same code, so what you read is what you would get.
- Choose, then apply. Tick the pages you want. The rest are untouched.
- Undo. Each run records the page versions it changed, so a migration can be reverted. Re-scanning afterwards finds nothing left to do — which is what makes running it twice safe.
What can be read today
This is the part to read before planning anything. A macro we cannot read is reported and left exactly as it is — never rewritten, never emptied, never guessed at.
| The app you have | Today |
|---|---|
| Open API (Swagger) Integration — Toshihiro Sato | Migrates. A macro with a pasted specification is converted. A macro pointing at a URL is reported and left alone: that parameter has not been read off a real macro yet. |
| Open API Documentation — O'Hara Group | Detected and reported. Not rewritten. |
| Visualize OpenAPI (Swagger) — Dutch Beginners | Detected and reported. Not rewritten. |
| Swagger UI for Confluence — Tech Labs | Detected and reported. Not rewritten. |
| Open API (Swagger) Editor — EliteSoft | Detected and reported. Not rewritten. |
| Macro Pack — Warsaw Dynamics | Detected and reported. Cannot be rewritten, and this one is structural: it is a single generic macro that also renders PlantUML, Mermaid and LaTeX, and the page body does not say which. Changing one could destroy a diagram. |
Why "detected but not rewritten" instead of a best guess. To convert a macro we have to know which of its stored fields holds the specification. Published descriptors give us the field names; they do not prove which one a real macro of that vendor actually fills. Guessing wrong replaces a working API page with whatever string happened to sit at the guessed name — silently, on every page at once. A macro we leave alone still renders through the app you already have.
The list above grows as each vendor's macro is read against a real install. It is the current state, not a roadmap.
The warning worth reading
The dry run flags macros that are storing a username, a password or an access token.
This matters more than it sounds. In several of these apps those fields are ordinary macro parameters, which means they are written into the page body — and anyone who can read the page can read them. It is the one security complaint this category's customers actually make, in their own words:
"the document URL is displayed under the Swagger title including the Git token that allows access to the code in our repos which we do not want."
Our migration detects those fields so it can warn you, and never reads, stores or carries them across. If a macro is using one, treat it as a credential to rotate, not as configuration to move.
We do not accept repository credentials at all — see Limitations for what that rules out.
Two things a migration cannot fix
- A specification that was never valid. If what is stored is not a parseable OpenAPI or Swagger document, the dry run says so and skips it, rather than writing a broken macro.
- A page you cannot edit. The scan runs as you, with your permissions. Anything you cannot change is reported and skipped.
Questions before you start? Write to support@alidadeapps.com — including "does it handle our app", which is the one worth asking before you plan a switch.