Documentation

What you need

• Confluence Cloud.
• Specfold installed on your site. Installing an app needs a Confluence site administrator.
• An API specification as a YAML or JSON file: OpenAPI 3.0 or 3.1, Swagger 2.0, or AsyncAPI 2 or 3.

Specfold reads the specification as the person viewing the page, so Confluence permissions apply. A reader who cannot see the page or its attachment sees an error and no specification. The first time an app is used, Atlassian shows a consent screen. Approve it once.

Show a specification on a page in four steps

1. Create or open a page, for example API docs, and attach your specification file to it.
2. In the editor, type /openapi and choose OpenAPI and AsyncAPI viewer. The settings dialog API specification opens.
3. Under Where is the specification? leave A file attached to this page selected and choose the file under File. Below the list, a check tells you what Specfold found, for example "OpenAPI 3.0: Pet Clinic API v2.1.0, 7 operations, 12 models, no problems found".
4. Choose Save and publish the page.

Prefer not to attach a file? Choose Text pasted here instead and paste the specification into the settings. Pasted text is stored by Confluence in the page itself, so for bigger specifications attach the file.

Formats

YAML and JSON are both accepted. A file can be up to 4 MB. Pasted text can be up to 200,000 characters.

OpenAPI 3.2 and AsyncAPI versions above 3.0 are shown with the 3.1 and 3.0 features respectively.

Using the viewer

• Endpoints are grouped by tag, with side navigation. For AsyncAPI the first tab is Operations.
• Models shows schemas. For AsyncAPI the other tabs are Messages and Schemas. Schemas that use allOf are merged, oneOf and anyOf are shown with their discriminators, and recursive schemas open one level at a time.
• Search covers method, path, summary, operation id, tags, parameters and the start of descriptions.
• Examples are the ones written in the specification. Where there are none, Specfold generates sample data from the schema. Every HTTP operation also has a cURL command to copy. Nothing is ever sent.
• Links to one operation: the link icon next to an operation copies the address of the page with the operation selected. Opening that address opens the operation and scrolls to it.
• Colours: the viewer follows the theme of Confluence, light or dark. Each reader can also switch between automatic, light and dark with the button at the top right of the viewer.

Descriptions in a specification may use Markdown. It is shown as formatted text, never as HTML.

Compare two versions

In the macro settings, choose Compare with (optional) and pick an older file that is attached to the page. The viewer gets a Changes tab that lists added, removed and changed operations and models. Changes that may break existing clients are marked potentially breaking. That marker is a heuristic and an aid, not a guarantee.

Keep the documentation current

The viewer always shows the newest version of the attached file. To update the documentation, upload a new version of the same attachment. The page itself does not need to change.

If your specification is built by a pipeline, add a step that uploads it to the page with the Confluence REST endpoint for updating attachment content. The documentation then follows every release.

Macro settings

When something is wrong with the file

You get a readable message instead of a blank macro:

• Syntax errors in YAML or JSON are shown with the line, the column and a snippet of the source.
• Unknown fields come with a "did you mean" suggestion.
• Unresolved or external references are explained. See the note on references below.
• More than sixty other checks cover missing fields, wrong types, duplicate operation ids and similar problems.

A specification with warnings is still displayed, with a banner above it that lists them.

References to other files

Specfold reads one self-contained file. A $ref that points to another file or to a URL cannot be followed. Bundle the references into one file first (most API tooling has a bundle command), then attach the bundled file.

Moving from a Connect macro

Atlassian ends support for apps built on Atlassian Connect, and older OpenAPI and Swagger macros are among them. To switch:

1. In the old macro, note where the specification comes from and download the file, for example from your repository or API gateway.
2. Attach the file to the Confluence page, insert OpenAPI and AsyncAPI viewer and pick the file.
3. Keep it current by uploading new versions of the same attachment, by hand or from a pipeline.
4. Remove the old macro.

Limits

• No specification from a URL and no external references. The specification comes from the page.
• No Try it out. The cURL examples are samples generated from the specification.
• Not shown: if/then/else, dependentSchemas and $dynamicRef. patternProperties is listed but not evaluated.
• AsyncAPI payloads in another format than JSON Schema (for example Avro or Protobuf) are shown as raw text. The reply part of AsyncAPI 3 is not shown.
• Images in descriptions are not loaded. Links in descriptions open through Confluence, which asks you before it opens a new tab.
• The macro is a placeholder in PDF and Word exports of the page.
• A link to one operation scrolls only when the macro has a fixed height.
• Readers need a Confluence account with access to the page. Anonymous access is not supported.

Permissions and data

Specfold asks for one permission, read:attachment:confluence, and uses it as the person viewing the page. It stores nothing. See Security and the Privacy Policy.

Need help?

See the support page for how to reach us, what to include and answers to common questions.