Surfaced

Specdock: API docs and diagrams in Confluence

Specdock is a Confluence Cloud app that renders API specifications and diagrams on any page: OpenAPI 3.x, Swagger 2.0 and AsyncAPI specs, plus Mermaid and PlantUML diagrams. It is built on Atlassian Forge, so your pages and settings stay in Atlassian.

What you can put on a page

  • OpenAPI / Swagger docs macro: a searchable API reference with operations and schemas.
  • Mermaid diagram macro: sequence, flowchart, ER and state diagrams from Mermaid text.
  • PlantUML diagram macro: sequence, class, component and activity diagrams from PlantUML text.

Where the spec can come from

  • A .yaml or .json file attached to the page.
  • A file in a GitHub, GitLab or Bitbucket Cloud repository, optionally pinned to a branch or tag. The page shows the current version of the file, so the docs don't go stale.
  • A public https URL (hosts allowed by your Confluence admin).
  • A spec pasted into the macro.

Breaking-change report

In the macro settings, choose an older version to compare with (another attachment, or a branch or tag). Specdock lists removed operations and other changes that could break existing API clients, sorted into breaking changes, warnings and other changes.

Private repositories

A Confluence admin opens Settings → Specdock settings and adds a read-only access token for the Git host once. The token is kept in Forge secret storage. It is never shown in page source or to page editors, and it is sent only to the host it belongs to.

Moving off a retired Swagger, Mermaid or PlantUML app

Many Confluence Connect apps are no longer updated, and Atlassian ends Connect support on January 31, 2027. In Specdock settings, the migration scanner lists the pages in a space that still use an older Swagger/OpenAPI, Mermaid or PlantUML macro, with the spec or diagram text each one uses, so you can move them to Specdock page by page.

Getting started

  1. A Confluence admin installs Specdock from the Atlassian Marketplace.
  2. Edit a page, type / and choose OpenAPI / Swagger docs, Mermaid diagram or PlantUML diagram.
  3. Pick the source, click Test source, then save and publish the page.

Pricing

Free for up to 10 users. Above that it is billed per user per month through Atlassian.

Privacy and security

Specdock stores no personal data. It keeps admin-added Git tokens in Forge secret storage and caches fetched specs for up to 5 minutes in Forge storage. See the privacy policy and terms.

Support

Email getsurfaced@proton.me (Zeustable, the company behind Specdock, Askbase and Surfaced). We reply within one business day.