Specpane: User guide
Specpane: OpenAPI Viewer for Confluence
Show interactive API documentation on any Confluence page, from a page attachment, a Git repository, or pasted text.
Add a viewer to a page
- Edit a page and type
/OpenAPI. If it doesn't appear, choose View more and search for "Specpane". - Choose where the spec comes from:
- File attached to this page: attach a
.yaml,.ymlor.jsonfile to the page, then pick it from the list. If you just attached it, click Refresh. - Git repository: paste a link to the file on GitHub, GitLab or Bitbucket, and the fields fill in. For a private repository, pick a connection your Confluence admin has set up.
- Paste the spec: paste YAML or JSON. This works best for small specs.
- File attached to this page: attach a
- Check the preview, then click Save and publish the page.
You can add as many viewers to a page as you like.
Display options
| Option | What it does |
|---|---|
| Operations | Shows the operation list collapsed, expands everything, or collapses whole tags |
| Only show these tags | Comma-separated tag names, such as pets, store. Leave it empty to show all. |
| Show servers | Shows or hides the server list |
| Show schemas | Shows or hides the Schemas section |
| Show tag search box | Adds a box that filters operations by tag |
The tag filter and Show servers also apply to PDF and Word exports.
Git repositories
- Public repositories work without a connection. Unauthenticated requests share a small provider rate limit, though, so busy sites should use a connection even for public repositories.
- Private repositories need a connection, which a Confluence admin creates (see below).
- Updates: changes pushed to the repository appear within 5 minutes.
- Default branch: leave Branch, tag or commit empty to use the repository's default branch.
- Branch names containing
/: a pasted link can't tell where such a branch name ends. Type the branch name into the field yourself.
For Confluence admins: Git connections
Open Settings (the gear icon), then Apps > Specpane in the sidebar. The quickest way is to type "Specpane" into Jump to setting. You can also use the app's Configure link in app management.
Each connection has:
- Name: what page authors see when choosing a connection
- Provider: GitHub, GitLab or Bitbucket Cloud
- Access token, created as follows:
- GitHub: a fine-grained personal access token with read-only Contents permission, limited to the repositories that hold specs.
- GitLab: a personal, group or project access token with the
read_apiscope. - Bitbucket: a repository, project or workspace access token with Repositories: Read. For an Atlassian API token, also enter the account email.
- Limit to spaces: optional space keys, such as
ENG, API. Leave it empty to allow all spaces.
About tokens:
- They are stored encrypted and are never shown again. To replace one, edit the connection and paste a new token. Leaving the field blank keeps the current token.
- Anyone who can edit a page in an allowed space can display any file the token can read. Use tokens limited to the repositories that hold API specs.
Exporting to PDF and Word
In exports, each viewer becomes the API's title, version, description and servers, followed by one table per tag listing each operation's method, path and summary.
Troubleshooting
| Message | What to do |
|---|---|
| "No spec files on this page yet" | Attach a .yaml, .yml or .json file, then click Refresh. |
| "...couldn't find that file" | Check the repository, branch and path, and that the connection's token can read that repository. |
| "...rejected the access token" | The token expired or was revoked. Ask an admin to update the connection. |
| "...connection isn't available in this space" | An admin limited the connection to other spaces. |
| "Confluence didn't allow the app to..." | A data security policy may block apps in this space. An admin can check Marketplace and custom app access in Atlassian Administration. |
| "This doesn't look like an OpenAPI or Swagger document" | The file needs a top-level openapi or swagger field. |
"Try it out" isn't available. Confluence's security policy blocks requests from inside pages to other servers, so the button would always fail. It's hidden instead.