Specpane: User guide

Specpane: OpenAPI (Swagger) 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

1. Edit a page and type /OpenAPI. If it doesn't appear, choose View more and search for "Specpane".
2. Choose where the spec comes from:
   • File attached to this page: attach a .yaml, .yml or .json file 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.
3. Check the preview, then click Save and publish the page.

You can add as many viewers to a page as you like.

Display options

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_repository scope. Project and group tokens need the Reporter role or higher. (read_api also works but gives more access than Specpane needs.)
  • Bitbucket: a repository, project or workspace access token with Repositories: Read. Atlassian account API tokens aren't supported.
• 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.

Ask Rovo about your API

If your site has Rovo, Specpane adds the Specpane API Docs agent. It answers questions from the specs on a page, such as:

• Which endpoint do I use to book an appointment?
• What does the request body for POST /orders need?
• What can GET /orders/{id} return?
• How do I authenticate with this API?

It can also write example requests in curl or the language you ask for, using the spec's server URL and placeholders such as YOUR_API_KEY for secrets.

To ask:

1. Open the page with the Specpane viewer.
2. Open Rovo chat, choose Specpane API Docs in the agent list (search for "Specpane"), and ask your question.

To ask about a different page, paste that page's link into your question.

What the agent can read:

• Specs shown with Specpane on the page: attached files, pasted specs, and files from Git repositories.
• Other .yaml, .yml or .json OpenAPI files attached to the page, even if no viewer shows them.
• Specs from a private repository (through a connection) only after someone has viewed the page since the viewer was added or changed. Until then the agent says it can't read them yet.

The agent reads Confluence as the person asking, so it never answers from a page or attachment they can't open. It only reads specs: it can't call your API, change a spec or edit the page. Answers come from the spec. When the spec doesn't describe something, the agent says so rather than guessing, but check important details against the viewer, as with any AI answer.

The agent is included with Specpane. Rovo counts its use toward your site's Rovo usage, as it does for any agent.

MCP tools. The agent's four actions are also available as MCP tools: list specs, search operations, get an operation, and get a schema. You can add them to agents you build in Rovo Studio. Once an admin allows it, outside AI tools that support MCP can use them too. This is a preview feature from Atlassian and may change.

Troubleshooting

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

Support

support@brainstaticthreads.com