# 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](https://help.gocapable.com/images/ded298c0-6e98-46d5-b77b-6c94829887d6.webp) 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 \`. 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. | --- ## Related [CodeA read-only code block with syntax highlighting, optional line numbers, a copy button and a cho](https://help.gocapable.com/macros/code.html) [LaTeX mathRenders a block mathematical equation written in LaTeX, centred on its own line in the page.](https://help.gocapable.com/macros/latex-math.html) [Technical and dataThe rest of this family.](https://help.gocapable.com/macros/technical-and-data.html) --- _The largest family, and the most precise._