Streamline API Documentation: Embed Swagger from GitHub to Confluence

Phanindra Mangipudi -

The Problem: Manual Copy-Pasting Swagger YAML/JSON

Swagger is a beautiful way to document APIs. Recently, while working on design documents in Confluence, I manually copied and pasted Swagger YAML/JSON to preview the API documentation. While this works, it’s not scalable and introduces several issues:

  • Human errors (incorrect copy-pasting, formatting issues)
  • No syntax validation (mistakes in YAML/JSON go unnoticed)
  • Versioning challenges (keeping docs in sync with code changes is tedious)

The Solution: Embed Swagger Directly from GitHub

Instead of copying Swagger definitions manually, we can fetch them directly from a GitHub repository. This ensures:

Real-time updates (changes in GitHub reflect automatically in Confluence)
Version control (track changes via Git history)
Collaboration-friendly (developers update Swagger in code, not Confluence)

Step-by-Step Implementation

Step 1: Generate a GitHub Personal Access Token (PAT)
Since the repository is private, we need a PAT to fetch the Swagger file.

  1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens.
  2. Create a new token with the following permissions:
    • repo (to access private repositories)
    • (Optional) Restrict access to specific repos for security.

Step 2: Get the Raw File URL from GitHub

Instead of using the regular GitHub URL, we need the raw file link (which bypasses the GitHub UI).

  1. Find the file in your repository (e.g., swagger.yaml).
  2. Click "Raw" to get the direct URL. for eg.m https://raw.githubusercontent.com/{username}/{repo}/{branch}/{path-to-file}
  3. Never include the branch name in the final URL if you want it to always fetch the latest version.

Step 3: Use the GitHub CLI (Optional)

If you prefer automation, use the GitHub CLI to fetch the file:
gh api repos/{owner}/{repo}/contents/{path-to-file} --jq '.download_url'

This returns the direct download URL, which you can use in Confluence.

Step 4: Embed in Confluence

<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<div id="swagger-ui"></div>
<script>
  fetch('https://raw.githubusercontent.com/{user}/{repo}/{path-to-file}')
    .then(response => response.text())
    .then(yaml => {
      const ui = SwaggerUIBundle({
        spec: YAML.parse(yaml),
        dom_id: '#swagger-ui'
      });
    });
</script>

Benefits of This Approach

No more manual updates – Docs stay in sync with the codebase.
Better collaboration – Developers update Swagger in GitHub, not Confluence.
Version-controlled – Track changes via Git history.

Final Thoughts

By embedding Swagger directly from GitHub, we eliminate manual errors, improve maintainability, and keep documentation up-to-date effortlessly.

Try it out and say goodbye to copy-pasting Swagger forever!