Migrating from a Connect-based Swagger macro

Why you need to move

Atlassian is ending support for Connect apps on 31 January 2027. Admins have been seeing an "unsupported after January 2027" banner for apps that have not moved to Forge. Many Swagger and OpenAPI macros for Confluence are Connect-only, and their vendors have not published Forge versions. After the end-of-support date those macros may stop working, and your pages would show an error or an empty box instead of your API reference.

OpenAPI Viewer is built on Forge and is Runs on Atlassian. It also solves the private-repository problem without storing a token: your pipeline pushes the spec to the page.

Five steps

1. Inventory

List the pages that use the old macro. Check whether your old app offers a usage list, then search Confluence for pages you know document APIs. Note for each page where the spec comes from: pasted text, an attachment, or a URL.

2. Collect the specs

For pasted specs, copy the text out of the old macro's configuration. For specs loaded from a URL, download the file from its source. Version 1 of OpenAPI Viewer does not fetch from URLs (see FAQ), so every spec becomes either pasted text (up to about 150 KB) or a page attachment.

3. Install OpenAPI Viewer

Install it from the Marketplace alongside the old app. Do not uninstall the old app yet. The trial is 30 days, and sites with 10 users or fewer are free. See the quick start.

4. Replace the macros page by page

On each page: add the OpenAPI Viewer macro, choose paste or attachment mode, compare the output with the old rendering, then delete the old macro. For specs that used to come from a URL or a private repository, set up the CI push so the page keeps updating. Start with your most visited pages.

5. Verify and clean up

Reload each page as a normal reader, check deep links to operations, and check dark mode. Then uninstall the old app, well before the end-of-support date, and keep the list from step 1 as a record.

Things that will differ

• No "Try it out" and no URL fetch (see FAQ).
• $ref to other files needs a bundled single file for now.
• Old links that point at an operation inside the previous macro will not carry over. New deep links start from the new macro.

Feature map

What OpenAPI Viewer offers. The per-app comparison (what the previous app does, and what changes) is in the vendor guides below.

Vendor guides

• Open API (Swagger) Integration
• Swagger UI for Confluence (Tech Labs)
• Open API (Swagger) Editor for Confluence (EliteSoft)

No guide yet for the Dutch Beginners app; the five steps above apply to it as well.