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
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.