Swagger/OpenAPI

Embeds full Swagger UI API reference documentation from a URL, a page attachment, or a spec pasted inline.

Put your API's reference documentation on the Confluence page where people already look for it, instead of linking away to a separate portal. It renders the standard Swagger UI - grouped endpoints, expandable operations, schemas and examples - from an OpenAPI 3 or Swagger 2 document. Where your site admin has approved the API's own domain for direct browser access, the "Try it out" controls also light up so readers can call real endpoints from the page, with an API key, bearer token or basic credentials you configure once. Otherwise the macro is read-only documentation, which is the safe default.

#See it

Every example below is a real macro on this page, not a screenshot, and each one is a configuration taken from a page somebody actually built. Open this page in the editor to see how any of them is set up.

Loading API documentation…

#Settings

The Capable macro configuration dialog for Swagger UI, previewing the Swagger Petstore reference on the left, and on the right a URL, Attachment and Inline source switch above a documentation URL fiel — The source is chosen first, from a URL, a page attachment or a spec pasted inline, with well known APIs offered as suggestions.

Setting	Values	What it changes
Swagger Documentation URL	Any http(s) URL to a JSON or YAML spec. A picker offers seven built-ins: Petstore API (Capable-hosted sample), Confluence REST API, Jira REST API, Mailchimp API, Spotify API, Twilio API, Twitter API. A "Find Swagger/OpenAPI URLs" link opens apis.guru.	The spec is fetched through Capable's authenticated URL proxy, so cross-origin restrictions on the spec host do not apply. Selecting the URL tab clears the attachment and inline fields.
Attachment	A file attached to this page. The list is filtered to JSON/YAML/OpenAPI media types (application/json, text/plain, application/yaml, application/x-yaml, text/yaml, text/x-yaml, application/vnd.oai.openapi[+json], application/vnd.swagger.v2+json, application/openapi+json); attachments with no declared media type are shown too.	Downloads the attachment over the Confluence bridge as the signed-in reader and parses it (JSON if it parses, otherwise handed to Swagger UI as text). Selecting the Attachment tab clears URL and inline spec.
Swagger Documentation Specification	A spec pasted into a JSON code editor.	Stored compressed: the text is deflated with pako and base64-encoded before it goes into the page config, and inflated again on both the config and view sides. Selecting the Inline tab clears URL and attachment.
Authentication	None, API key, Bearer token, Basic auth	What gets attached to every "Try it out" request. The entire authentication section is HIDDEN unless the spec's API host is already approved for client-side egress - there is nothing to authenticate against otherwise.
Key name	Header or query-parameter name, e.g. X-Api-Key or api_key	Only shown and used when Authentication is API key.
Key value	Free text, masked as a password field	The API key value. Only for API key auth.
Send in	Header, Query parameter	Whether the API key goes in a request header or is appended to the URL's query string. Only for API key auth.
Bearer token	Free text, masked	Sent as `Authorization: Bearer <token>`. Only for Bearer auth.
Username	Free text	Basic auth user; combined with Password and sent base64-encoded as `Authorization: Basic …`. Only for Basic auth.
Password	Free text, masked	Basic auth password. Only for Basic auth.
Send cookies	on / off	Sets Swagger UI's `withCredentials`, so the browser includes cookies with try-it-out requests. Only shown when the auth block is visible.

Code

A read-only code block with syntax highlighting, optional line numbers, a copy button and a cho

LaTeX math

Renders a block mathematical equation written in LaTeX, centred on its own line in the page.

Technical and data

The rest of this family.

The largest family, and the most precise.