Repo Docs: OpenAPI & Markdown from Git

Two Confluence Cloud macros: OpenAPI Docs (OpenAPI 3.x, Swagger 2.0) and Markdown from Git (with Mermaid and repo images). Files are fetched on every page view, so pages follow the branch or tag you choose.

openapi: 3.0.3
info:
  title: Orders API
paths:
  /orders:
    get:
      summary: List orders
    post:
      summary: Create an order
  /orders/{id}:
    get:
      summary: Get one order
  /orders/{id}/refund:
    post:
      summary: Refund an order

# Release process

1. Merge to main
2. CI builds the image
3. Deploy to staging
4. Announce the release

```mermaid
graph LR
  Merge --> Build --> Deploy
```

Set up in two steps

1. 1

   Add a read-only token

   Site admins, private repos only.

   Go to Settings → OpenAPI Docs and save one token per Git host. It is stored in Atlassian's encrypted app storage and never shown to page viewers or editors.

   GitHubBitbucketGitLab
   • GitHubFine-grained personal access token limited to the repos that hold your docs, with Contents: Read-only.
   • Bitbucket CloudRepository or workspace access token with Repositories: Read.
   • GitLab.comProject or group access token with read_repository (or read_api).

   Use tokens that can only read the repositories you want shown: anyone who can edit a page can display any OpenAPI or Markdown file those tokens can read.

2. 2

   Insert a macro

   Edit a page, then type /OpenAPI Docs or /Markdown from Git.

   ProviderGitHubRepositoryacme/ordersFile pathopenapi.yamlBranch, tag or commitmain

   Fill in these four fields; the repository is owner/repo, workspace/repo or group/project, depending on your host. Made-up values, not a screenshot.

What gets rendered

Troubleshooting

Still stuck? Contact support.