Attachment mode: render a spec attached to the page
Attachment mode renders an OpenAPI file that is attached to the same Confluence page as the macro. It is the right choice when your spec is larger than the paste limit, when you want to keep one source file, or when you want the page to update without anyone editing it.
Attach the file
- Open the page and click Edit.
- Attach your spec. Drag the file onto the page, or use Insert > Files and images, or the page's attachments view.
- The file must end in
.yaml,.yml, or.json. Other extensions are not listed in the picker. - Publish the page. The attachment is stored by Confluence in the normal way, like any other attachment.
Spaces in file names cause trouble in scripts, so a plain name such as openapi.yaml is a good choice. If you plan to update the file from CI, choose the name once and keep it (see CI push).
Point the macro at the file
- Add the OpenAPI Viewer macro (type
/openapi). - Set Source to Attachment.
- Choose the file from the Attachment list. Only
.yaml,.yml, and.jsonfiles on the current page are shown. - Choose a version mode, described below, and click Save.
Latest vs. pinned version
| Mode | What readers see | Use it when |
|---|---|---|
| Always latest (default) | The newest version of the attachment, every time the page is loaded | The page should track your current API, or a pipeline keeps the file up to date |
| Pinned version | A specific version number you choose, even after newer versions are uploaded | The page documents a released API version and must not change under readers |
Confluence keeps every uploaded version of an attachment. To see them, open the page's attachments view and expand the file's version history. Pinning refers to that version number. If you later delete that version, the macro will report that the attachment cannot be found.
Update the spec without editing the page
This is the main advantage of attachment mode. In "always latest" mode:
- Upload a new version of the file with the same name. You can do this by hand (attach a file with the same name and choose to upload a new version when Confluence asks) or from CI using the REST call in the CI push guide.
- Readers see the new version the next time they load or refresh the page. The page content itself is not edited.
Uploading a file with a different name creates a second attachment instead of a new version. Keep the name stable.
Size limits
- Pasted specs are capped at roughly 150 KB. Attachment mode has no such cap.
- Attachments are subject to the maximum attachment size configured for your Confluence site (an admin setting). The app does not add its own small limit, but very large documents take longer to parse and display. See "Performance" in the FAQ.
Permissions
The macro reads the attachment as the person viewing the page. Anyone who can view the page can see the rendered spec. If the page is restricted, only people with access to the page can see the rendered output. If someone sees a permission error, see Troubleshooting.
Files with references to other files
If your spec uses $ref to point at other files (for example ./schemas/pet.yaml), those references are not resolved in version 1. Bundle the spec into one file first. For example, with Redocly CLI:
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yamlThen attach or push dist/openapi.yaml. Multi-file support is planned. See the FAQ.