SpecDock Documentation

SpecDock renders OpenAPI 3.x and Swagger 2.0 specifications (JSON or YAML) on Confluence pages, fetched at view time so they never go stale.

Getting started

Edit any Confluence page and type /SpecDock to insert the macro.
The configuration form opens. Pick a source and fill in the coordinates of your spec (see below).
Click Save and render. The documentation renders in place.
To change the configuration later, edit the page and click Edit source… above the macro.

For the best reading experience with the navigation sidebar, set the Confluence page to full width (page width toggle in the editor). In narrow pages the navigation collapses automatically, like on mobile.

Sources

GitHub

Field	Value
Repository	`owner/repository`
File path	e.g. `docs/openapi.yaml`
Ref	branch, tag, or commit (default `main`)
Token (private repos)	Fine-grained personal access token with Contents: Read-only on that single repository. Nothing else.

GitLab.com

Field	Value
Repository	`group/project`
Token (private repos)	Project access token with the read_repository scope and Reporter role.

Self-managed GitLab instances are not supported yet — only gitlab.com. Tell us if you need this: [email protected].

Bitbucket Cloud

Field	Value
Repository	`workspace/repository`
Token (private repos)	`username:app_password` — an app password with only Repositories: Read.

Raw URL

Any https:// URL on these hosts: raw.githubusercontent.com, gitlab.com, api.github.com, api.bitbucket.org. Other hosts are not reachable by design — the app declares a fixed, minimal egress list to Atlassian.

Pasted spec

Paste the spec (JSON or YAML) directly, up to 100 KB. For larger specs, use a Git source.

How tokens are handled

Tokens are stored in Forge encrypted secret storage, hosted by Atlassian.
They are used exclusively server-side to fetch your spec.
They never reach the page content, the editor, or the browser — the frontend only ever knows whether a token is saved.
Deleting the macro removes its configuration; uninstalling the app removes all stored data, per Atlassian's Forge storage lifecycle.

Layouts

Full documentation: three-pane reading view with a navigation sidebar. Compact endpoint list: a single-column list, useful when several specs share a page. Each macro has its own layout setting.

"Try it out"

Off by default. Requests run from the reader's browser, so they are subject to your API's CORS policy — if the API doesn't allow the Confluence origin, calls will fail. That is a browser security constraint, not something an app can bypass. Enable it per-macro only if your API's CORS setup allows it.

Troubleshooting

Message	What it means
`HTTP 401/403 — check the access token`	Token missing, expired, or lacking read permission on the repo.
`HTTP 404 — check repo/path/ref`	Wrong repository, file path, or branch name.
`The spec could not be parsed`	The file isn't valid JSON or YAML.
`Host not allowed yet`	Raw URLs are limited to the hosts listed above.

Support

Email [email protected]. Include your source type and the exact error message; never include your access token.