Guides / OpenAPI

Show an OpenAPI or Swagger specification in Confluence Cloud

The API specification is usually in the repository, next to the code that implements it. SourceDocs shows that file on a Confluence page as a readable API reference, so product managers, support and partners read the same version the developers ship.

Steps · What readers see · Which version is shown · PDF export · Questions

Steps

Install SourceDocs for Confluence from the Atlassian Marketplace. A Confluence admin does this once for the site.
Open the specification file (openapi.yaml, swagger.json or similar) in GitHub, GitLab, Bitbucket Cloud or Azure DevOps and copy the address from the browser bar.
In Confluence, type /git, pick SourceDocs: File from Git, paste the link and click Preview.
Save and publish the page.

SourceDocs recognises the file as an API specification by its openapi or swagger field, in YAML or JSON. OpenAPI 3.0, OpenAPI 3.1 and Swagger 2.0 are supported. Specifications in private repositories work after an admin stores a read-only token once; see private repositories.

What readers see

Navigation by tag and operation, with search. Large APIs (more than 30 paths) appear in their own scrolling window with the menu kept in view.
Descriptions and parameters for each operation.
Request and response bodies with schemas and examples.
A layout that follows Confluence's light or dark mode.

There is deliberately no "Try it out" button. Nothing is sent to your API from the page, so a reference shared with a wide audience cannot be used to call production by accident.

Which version is shown

The branch or tag in the link decides what readers see. A link to main shows the current development state and picks up changes within 10 minutes. A link to a release tag such as v3.2.0 shows the specification exactly as released. Two macros on one page, one per version, let readers compare a release with what is coming next.

PDF export

PDF and Word export turn the specification into a printable reference: one section per operation with tables for parameters, request body and responses, example JSON, and a schema section. It is useful for partner handovers and audits.

Questions

Can the specification be split across several files?

Not yet: SourceDocs shows one file, and $ref references to other files are not followed. Bundle the specification into one file first, for example in your CI build, and point the macro at the bundled file.

How large can the specification be?

Up to 16 MB. GitHub's own REST API description, 13.5 MB with about 1,500 operations, works, and takes about 15 seconds to draw. Specifications of a single service usually appear within a second or two.

Is the specification sent anywhere?

The file is fetched by Atlassian's Forge platform from your Git provider and rendered in the reader's browser. There is no SourceDocs server. See the security page.

What does it cost?

Free for Confluence sites with up to 10 users. Above that, from 0.45 USD per user per month, with a 30-day free trial on the Marketplace.

SourceDocs for Confluence renders OpenAPI, Markdown, Mermaid, PlantUML and code files from GitHub, GitLab, Bitbucket and Azure DevOps. The Marketplace listing is in review. Read the documentation or write to [email protected].

More guides: Mermaid in Confluence · PlantUML in Confluence · Files from GitHub and GitLab in Confluence · Markdown in Confluence