OpenAPI & Swagger Viewer for Confluence

Show an OpenAPI 3.0, 3.1 or Swagger 2.0 spec as readable API documentation inside a Confluence page, in the Swagger UI layout your team knows.

Getting started

1. Edit a page, type /OpenAPI and choose OpenAPI Viewer.
2. Choose where the spec comes from:
   • Paste it into this page: paste YAML or JSON. The editor checks it as you type and points to the exact line of any error. The spec is stored in the page, so it is versioned with the page history.
   • Use a .yaml or .json attachment: pick a file attached to this page or to another page (paste its link). The page always shows the file's newest version.
3. Choose how endpoints start (collapsed by tag, expanded, or tags only), then Save and publish the page.

You can put several specs on one page. The viewer follows Confluence's light or dark theme.

Keep the spec in sync with your repository

Point the macro at an attachment, then have your CI upload the spec on every merge. PUT …/child/attachment adds a new version when a file with the same name exists.

1. Attach openapi.yaml to the page once and select it in the macro.
2. Note the page ID (the number after /pages/ in the page URL).
3. Create an Atlassian API token for an account that can edit the page and store it, with the account's email, as CI secrets.

GitHub Actions

name: Publish API spec to Confluence
on:
  push:
    branches: [main]
    paths: [openapi.yaml]
jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Upload openapi.yaml as a new attachment version
        env:
          SITE: https://your-site.atlassian.net
          PAGE_ID: "123456"
          AUTH: ${{ secrets.CONFLUENCE_EMAIL }}:${{ secrets.CONFLUENCE_API_TOKEN }}
        run: |
          curl --fail -sS -u "$AUTH" -X PUT \
            -H "X-Atlassian-Token: nocheck" \
            -F "file=@openapi.yaml" -F "minorEdit=true" \
            "$SITE/wiki/rest/api/content/$PAGE_ID/child/attachment"

Bitbucket Pipelines

pipelines:
  branches:
    main:
      - step:
          name: Publish API spec to Confluence
          script:
            - >-
              curl --fail -sS -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" -X PUT
              -H "X-Atlassian-Token: nocheck"
              -F "file=@openapi.yaml" -F "minorEdit=true"
              "https://your-site.atlassian.net/wiki/rest/api/content/123456/child/attachment"

The token stays in your CI. The app itself never connects to your repository.

Export to PDF and Word

Exports contain the API's title, version, description and servers, and one table of endpoints (method, path, summary) per tag, with deprecated operations marked. Specs with more than 400 endpoints show a count instead of a table.

Limits, and why

• No fetching from URLs or Git. The app never connects to servers outside Atlassian. Use an attachment and the CI recipe above.
• No "Try it out". Sending requests from a Confluence page to your API would require the app to reach outside Atlassian, and most APIs block such browser requests anyway.
• References to other files are not resolved. $ref within the same file works. Bundle multi-file specs first, for example npx @redocly/cli bundle openapi.yaml -o bundled.yaml.
• Size. Pasted specs up to 1 MB, attachments up to 5 MB. Specs with more than 250 operations start collapsed to tags.

Licensing

With an inactive license the page shows a notice and the spec as plain text: your content is never lost. Evaluation licenses get the full app.

Privacy and security

The app stores nothing, sends nothing outside Atlassian, and reads attachments as the viewing user. Permissions: read page attachments. Details: privacy policy, security.

Help

support@golden-dorado.com · Support