Documentation & support

OpenAPI Viewer & Macro Migrator for Confluence — user guide

Last updated: 13 October 2026

What it does

Two things. It shows an OpenAPI specification inside a Confluence page, with Swagger UI. And it replaces the macros of the Connect OpenAPI and Swagger apps that lose support on 31 January 2027 with its own macro, so your pages keep working.

Requirements

Showing a specification

In the editor, type /openapi or /swagger and pick OpenAPI (Swagger) Viewer. In the configuration, choose where the specification comes from:

OpenAPI 2.0 (Swagger), 3.0 and 3.1 are supported. Then set how it looks: expansion, sorting, tag filter, maximum tags, operation IDs, request duration, extensions, and whether to show the title and the source URL. Save, and publish the page.

Private repositories

Enter an access token, or a username and password, in the macro configuration. The app keeps them on the server, never in the page, and sends them only to the address they were saved for — the configuration tells you which one. To delete them, press Remove saved credentials. If you change the URL to a different host, enter them again for that host.

Try it out

Choose which HTTP methods can be tried (for example get,post, or none to switch it off). Requests are sent from your browser to the server described by the specification, so that API must accept requests from a browser on another site (CORS). If it does not, Swagger UI shows Failed to fetch — that is the API refusing, not the app.

Migrating the old macros

  1. Open Migrate OpenAPI macros: Confluence administration → Apps section (it may be collapsed), or Get started next to the app in your site’s connected apps.
  2. Search. The first search after a quiet period can take 10–20 seconds; the button says Searching… meanwhile. Up to 100 pages are listed at a time: convert them, then search again.
  3. Preview a page: how many macros will be converted, and any parameter that could not be carried over.
  4. Convert. The old macros become this app’s macro with the same address and display options; credentials in the old parameters are moved to the app’s server-side storage. Each conversion is a new page version, so the previous one stays in the page history.

Old macros inside other macros, such as an Expand, are found and converted too.

Frequent answers

“Only https addresses can be read.” The Atlassian Forge platform does not let apps read plain http. Publish the file over https, or attach it to the page.

“The address returned a web page (HTML), not an OpenAPI file.” The URL points to a page about the API, not to the file. Use the link to the raw .json or .yaml file.

“The specification server answered 401” or “403”. The file is private. Add a token or a username and password, and check that they were saved for this same address.

“Attachment … not found on this page.” The attachment must be on the same page as the macro, with exactly the name typed in the configuration.

“You cannot edit this page (Confluence permissions): nothing was changed.” On the migration page: your account cannot edit that page, for example because of a page restriction. Ask its owner, or convert it with an account that can.

“I cannot find the migration page.” Only Confluence administrators can see it. In the administration menu, open the Apps section at the bottom.

Contact

Open a request on our support portal, or write to support@pieranlab.cloud. Please include the exact message the macro shows and, if you can, the specification address.

See also the privacy policy and the security statement.