Keep the docs in sync

Publish a new version of your OpenAPI file to Confluence from GitHub Actions, GitLab CI, Bitbucket Pipelines or Azure DevOps.

Apifolio always shows the latest version of the attached file. To keep the docs in sync with your code, upload the spec as a new version of the same attachment from your CI pipeline. Confluence keeps every version, and readers see the new one the next time they open the page.

Everything below runs in your own CI: Apifolio itself never calls GitHub, GitLab, Bitbucket or Azure DevOps.

What you need

  • the page ID of the page that holds the spec (the number in the page URL, /pages/123456/...);
  • an Atlassian API token for a user who can edit that page, created at id.atlassian.com/manage-profile/security/api-tokens. Store it as a secret in your CI, never in the repository;
  • the file name used by the macro, for example openapi.yaml. Keep the same name so the macro finds the new version.

The request

curl --fail -sS -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" \
  -X PUT \
  -H "X-Atlassian-Token: no-check" \
  -F "[email protected]" \
  -F "minorEdit=true" \
  -F "comment=Updated from CI ($GIT_COMMIT)" \
  "https://your-site.atlassian.net/wiki/rest/api/content/$PAGE_ID/child/attachment"

PUT creates the attachment the first time and adds a new version afterwards. minorEdit=true avoids notifying page watchers on every build.

GitHub Actions

name: Publish API docs
on:
  push:
    branches: [main]
    paths: [openapi.yaml]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Upload openapi.yaml to Confluence
        env:
          CONFLUENCE_EMAIL: ${{ secrets.CONFLUENCE_EMAIL }}
          CONFLUENCE_API_TOKEN: ${{ secrets.CONFLUENCE_API_TOKEN }}
          PAGE_ID: "123456"
        run: |
          curl --fail -sS -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" -X PUT \
            -H "X-Atlassian-Token: no-check" \
            -F "[email protected]" -F "minorEdit=true" \
            -F "comment=Updated from ${GITHUB_SHA::7}" \
            "https://your-site.atlassian.net/wiki/rest/api/content/$PAGE_ID/child/attachment"

GitLab CI

publish-api-docs:
  image: curlimages/curl:latest
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: [openapi.yaml]
  script:
    - >
      curl --fail -sS -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" -X PUT
      -H "X-Atlassian-Token: no-check"
      -F "[email protected]" -F "minorEdit=true"
      -F "comment=Updated from $CI_COMMIT_SHORT_SHA"
      "https://your-site.atlassian.net/wiki/rest/api/content/$PAGE_ID/child/attachment"

Bitbucket Pipelines

pipelines:
  branches:
    main:
      - step:
          name: Publish API docs
          image: curlimages/curl:latest
          script:
            - curl --fail -sS -u "$CONFLUENCE_EMAIL:$CONFLUENCE_API_TOKEN" -X PUT -H "X-Atlassian-Token: no-check" -F "[email protected]" -F "minorEdit=true" "https://your-site.atlassian.net/wiki/rest/api/content/$PAGE_ID/child/attachment"

Azure DevOps

steps:
  - script: |
      curl --fail -sS -u "$(CONFLUENCE_EMAIL):$(CONFLUENCE_API_TOKEN)" -X PUT \
        -H "X-Atlassian-Token: no-check" \
        -F "[email protected]" -F "minorEdit=true" \
        "https://your-site.atlassian.net/wiki/rest/api/content/$(PAGE_ID)/child/attachment"
    displayName: Publish API docs to Confluence

What readers see

The footer of the macro shows when the file changed, its version and the comment of that version, for example:

openapi.yaml · Updated 3 days ago · version 7 · “Updated from 3f2a1c9” · 118 KB · OpenAPI 3.1.0 · History

Hover the date to see the exact time. History (for signed-in readers) opens the page's attachments, where Confluence lists every version of the file. Put the commit or build number in the comment field, as in the examples above, so readers can tell which build they are reading.

Confluence search and the Rovo agent use a digest saved with the macro, which an upload doesn't change. When the file is newer than the digest, editors see a note above the macro while editing the page: open the macro and click Save to refresh it. See Confluence search.

View as Markdown