Moving from another app
Replace Connect OpenAPI and Swagger apps for Confluence with Apifolio before Atlassian ends Connect support on 31 January 2027. The Apifolio dialog imports the old macro from the page.
Atlassian ends support for Connect apps on 31 January 2027. Several OpenAPI and Swagger apps for Confluence are built on Connect. Apifolio is built on Forge and Runs on Atlassian.
Guides for each app
- Open API (Swagger) Integration (Toshihiro Sato)
- Visualize OpenAPI (Swagger) documentation (Dutch Beginners)
- Swagger UI for Confluence (Tech Labs)
- Open API (Swagger) Editor for Confluence (EliteSoft)
- SwaggerHub Integration for Confluence (SmartBear)
- Open API Document Viewer (Absolute Technology Solutions)
Import the old macro from the page
When you insert Apifolio on a page that already shows an API with one of these macros, the Apifolio dialog finds the old macro in the published page and offers to import it:
| App (vendor) | Macros the dialog recognises |
|---|---|
| Open API (Swagger) Integration (Toshihiro Sato) | swagger-integration, swagger-open-api |
| Visualize OpenAPI (Swagger) documentation (Dutch Beginners) | swagger-open-api-macro |
| Swagger UI for Confluence (Tech Labs) | swagger-ui |
| Open API (Swagger) Editor for Confluence (EliteSoft) | confluence-open-api, open-api |
| Open API Document Viewer (Absolute Technology Solutions) | absolute-open-api |
| Swagger UI Integration (TinySoft) | tinysoft-swagger-ui |
| Swagger UI Viewer (Get Report) | swagger-macro |
| AwesomeAPI (UlterSolutions) | awesome-api-app-render-macro |
- Edit the page and type
/apifolio. The dialog shows "Found 1 Open API (Swagger) macro on this page" with what the old macro shows. - Click the button next to it. What happens depends on where the old macro took its spec from:
- The spec is pasted in the macro: Import checks it, attaches it to the page as a file named after the API title (for example
payments-api.yaml) and selects it. Importing the same spec again reuses that file. - A file attached to this page: Use this file selects it.
- A file attached to another page: Use this file opens that page under Another page and selects the file. When the old macro names the page by its title, Find the page searches for it: pick the page, then the file.
- A link to a file or a Git repository: Apifolio never downloads it. Download the file yourself, click Attach the file and choose it: it is attached to the page and selected.
- The spec is pasted in the macro: Import checks it, attaches it to the page as a file named after the API title (for example
- Check the preview. The old macro's display options that have an Apifolio equivalent are applied (see below), and the dialog lists the ones that have none.
- Click Save. Then delete the old macro from the page by hand and publish. Confluence keeps the page history, so you can restore the previous version.
Credentials stored in the old macro (user names, passwords, tokens, API keys, proxies, headers) are never copied, not even into the dialog: it only names them. They remain in the old macro and in the page history, so rotate them (revoke them and create new ones) and delete the old macro.
If the dialog doesn't offer an import, move the page by hand: attach the spec file to the page (or to a page you can link), insert Apifolio, choose the file and the display options, then delete the old macro.
Display options that carry over
Parameter names are compared without case and separators, so docExpansion, doc-expansion and DOCEXPANSION are the same.
| In the old macro | In Apifolio |
|---|---|
| The app rendered with Swagger UI | Classic (Swagger style) layout preselected (all the apps above except Open API Document Viewer and AwesomeAPI) |
docExpansion or expand set to full |
Expand endpoints by default (classic layout) |
tags |
Only these sections, for the names that exist in the file |
filter |
Only these sections: the sections whose name contains the text |
paths |
Only these paths |
operations or operationIds |
Only these endpoints, for the operation IDs (or methods and paths) that exist in the file |
showModels or hideModels, defaultModelsExpandDepth set to -1 |
Schemas list on or off |
defaultModelExpandDepth |
Schema fields: 0 collapsed, 1 first level, 2 or more all levels |
showInfo or hideInfo |
Introduction |
showServers or hideServers |
Servers |
hideDeprecated or showDeprecated |
Hide deprecated endpoints |
| Any other parameter | Listed in the dialog as "No Apifolio equivalent" |
Sections and endpoints that are not in the file are listed too, so nothing is dropped silently.
What does not carry over
- Try it out: Apifolio sends no live requests. Readers fill in the request with Edit request and run it in their own tools.
- URL and Git sources: attach the file to the page, and keep it up to date from your CI. See Keep the docs in sync.
- Stored credentials: there is nowhere to store them in Apifolio, by design.
- Specs split over several files (
$refto other files): bundle them into one file first. - AsyncAPI documents: Apifolio shows OpenAPI 3.x and Swagger 2.0 files.
See What Apifolio does not do, and why.
Moving many pages
To list the pages that use an old macro, search Confluence with CQL, for example macro = "swagger-ui" with the macro name from the table above. The import works one page at a time, in the Apifolio dialog: replacing macros across the whole site at once would mean that Apifolio edits your pages, which needs a permission it does not ask for.