# Getting started

Insert the Apifolio macro, choose an OpenAPI or Swagger file 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 configuration dialog opens automatically.

## 3. Choose your spec

Pick one of the sources on the left of the dialog:

- **This page**: a YAML or JSON file already attached to the page. Files that look like specs are listed first.
- **Upload a file**: attach a `.yaml`, `.yml` or `.json` file to the page from your computer.
- **Another page**: paste the link of another Confluence page and choose one of its attachments. Use this to show one spec on many pages. Readers need permission to view that page.
- **Paste**: paste a spec 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.

The preview on the right shows exactly what readers will see.

## 4. Adjust the display (optional)

Choose the layout, the height, which sections to show and which endpoints to include. See [Display options](/docs/display-options/).

## 5. Save and publish

Click **Save**, then publish the page. That's it.

When the file changes (for example when you upload a new version of `openapi.yaml`), the documentation updates automatically the next time the page is opened. To automate updates from Git, see [Keep the docs in sync](/docs/keep-in-sync/).

## Tips

- One page can hold several Apifolio macros, for example one per API or one per section of a large API.
- Spec files are never sent outside Confluence. See [Security](/security/).