Migrating from Open API (Swagger) Integration to OpenAPI Viewer for Confluence
If your Confluence Cloud pages render an OpenAPI or Swagger spec with the Open API (Swagger) Integration macro by Toshihiro Sato, this guide moves them to OpenAPI Viewer, an app built on Atlassian Forge and designed to be Runs on Atlassian: nothing leaves Atlassian, and the app stores no credentials. Allow about 30 minutes for a handful of pages.
Facts about the old app were checked on 13 October 2026 against its Marketplace listing and vendor documentation.
Why migrate now
Atlassian ends support for the Connect framework on 31 January 2027, and warns that breakages will increase afterwards. Since July 2026, Confluence admins have seen a banner on apps that still run on Connect, saying the platform will be unsupported after that date.
Open API (Swagger) Integration is listed as a Connect app (version 1.1.15-AC). Its latest Confluence Cloud release is dated 19 September 2024, and its listing shows no Forge version.
Feature map
| Open API (Swagger) Integration | OpenAPI Viewer | Status |
|---|---|---|
| Swagger UI engine (5.7.2 per listing) | Swagger UI-compatible renderer bundled in the app | Same |
| Swagger 2.0 and OAS 3.0 | OpenAPI 2.0, 3.0.x, 3.1 | Same (3.1 added) |
| Spec pasted in macro body | Paste source, up to about 150 KB | Same |
| Spec as page attachment (copy the attachment link into the URL field) | Attachment source: pick the file from a list, "always latest" or pinned version | Different, simpler |
| Spec from a hosted URL | Not supported | Not in v1. Workaround: CI push |
| Spec from GitHub, GitLab or Bitbucket (access token, or username and password, entered in the macro) | Not supported | Not in v1. Workaround: CI push, no token stored in the app |
| "Try it out" on each operation | Not supported | Not in v1. Workaround: Postman, curl, or your gateway console |
| Swagger Editor | Not supported | Not in v1. Workaround: edit in your repo or IDE |
| AsyncAPI (added in 1.1.15) | Not supported | Not in v1 |
| CORS must be enabled on the server hosting your spec | Not needed | Better |
| Search, expand/collapse, deep links, full-screen, auto-height, dark mode | Included | Same |
| Price: from USD 10/year at 10 users; USD 100 at 100; USD 275 at 500 | Free up to 10 users, then paid by user tier | Different |
Five steps
- Export each spec. For a pasted spec, open the page in the editor, open the old macro, and copy the body into a file such as
openapi.yaml. For an attached spec, the file is already on the page; no export is needed. For a spec loaded from a URL or Git, download the file from its source, or note the repository path for step 2. - Attach it, or set up CI push. Specs under about 150 KB can be pasted straight into the new macro. Anything larger, or anything that used to come from a URL or Git, goes in as an attachment on the page. To keep it fresh after every merge, add the pipeline from Push your spec from CI (ready-made pipelines are on that page).
- Install OpenAPI Viewer and replace the macro. Install it next to the old app (30-day trial). On each page add the new macro, choose Paste or Attachment, and delete the old macro. See the quick start and attachment mode.
- Verify. Reload as a normal reader. Check that every path and schema appears, that deep links to operations work, and that dark mode looks right. Compare against the old rendering for your most visited page first.
- Delete the old app. Once every page is checked, uninstall Open API (Swagger) Integration well before 31 January 2027. Your pages keep the new macro; the old app's data is not needed.
What you lose, and why
- Try it out. Sending live requests from a page requires external permissions on Forge, and an app with external permissions cannot be Runs on Atlassian. We chose the guarantee over the button. See the FAQ.
- URL and Git fetch. Any fetch is outbound traffic, which Runs on Atlassian does not allow. The old app's documentation has you enter a personal access token in the macro dialog, or add it to a GitLab URL. With the push model, your pipeline uploads the spec using your own Confluence token, held only in your CI secret store. The app never reaches your repository and never holds a credential.
- Editor and AsyncAPI. Not in version 1.