Getting started
Insert the Apifolio macro, choose an OpenAPI or Swagger file (or try the sample API) and publish interactive API docs in Confluence.
1. Install Apifolio
A Confluence site admin installs Apifolio from the Atlassian Marketplace (Confluence settings → Find new apps → search for "Apifolio"). Sites with up to 10 users can use it for free. Larger sites get a 30-day free trial.
2. Insert the macro
Edit a page, type /apifolio (or /openapi, /swagger) and choose Apifolio API Docs – OpenAPI & Swagger. The dialog opens automatically.
If the page already shows an API with another app's macro (for example Open API (Swagger) Integration or Swagger UI for Confluence), the dialog offers to import it. See Moving from another app.
3. Choose your spec
- Drop a file anywhere on the dialog, or click Upload a file. A
.yaml,.ymlor.jsonfile of up to 25 MB is checked and attached to the page. - This page: pick one of the YAML or JSON files attached to the page. When the page has exactly one, it is selected for you.
- Another page: paste a page link (short links from Share → Copy link work too) or a page ID, or type part of a page title and pick the page from the list. Pages that already use Apifolio come first. Readers need permission to view that page.
- Paste: paste a spec, check the file name and click Save as attachment. It is stored as a file on the page, so it is versioned with the page and follows its permissions.
Not ready yet? Click Try a sample API: the preview shows a fictional Payments API (22 endpoints, two servers, bearer authentication). Nothing is attached until you click Use this sample on the page (or Use sample and save, which also saves the macro).
The preview on the right shows what readers will see.
4. Adjust the display (optional)
Choose the layout, the height, which sections and endpoints to show, how schemas open, the density and the code languages. See Display options. Under the filters, the dialog shows how many endpoints Confluence search will find: see Confluence search.
5. Save and publish
Click Save, then publish the page.
When the file changes (for example when you upload a new version of openapi.yaml), readers see the new version the next time they open the page. The footer of the macro says when the file changed, with its version and version comment, and a History link to the file's versions. To automate updates from Git, see Keep the docs in sync.
Pages that are not published yet
Confluence doesn't list the attachments of a page that was never published. You can still upload, drop or paste a spec in the dialog: the file is attached to the draft, the preview works and Save builds the search index. If the macro on the page shows an error before the first publish, publish the page once.
When the subscription is not active
If the Apifolio subscription of the site is not active, the dialog says so. Readers then see a locked summary (the API title and its first 12 endpoints) until a site admin renews the subscription under Manage apps.
Tips
- One page can hold several Apifolio macros, for example one per API, or one per section of a large API. In current browsers, macros that show the same file share one download.
- To embed one endpoint in a how-to guide, pick it under Only these endpoints: with 1 to 3 endpoints the macro becomes a compact endpoint card.
- To show the same spec on another page, choose ⋯ → Embed this API on another page in the macro: it copies the page link to paste under Another page.
- Spec files are never sent outside Confluence. See Security.