> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logictwelve.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
> Configure Better Swagger UI for Confluence
There's no site-wide settings screen. The macro is configured individually, the first time you insert it on a page and any time afterward you choose to edit it.
## Better Swagger UI macro
Renders an OpenAPI or Swagger document as an interactive Swagger UI panel. Choose **OpenAPI document type** first — it determines whether you provide a URL or paste the document directly, and only the matching field is required.
| Field | Required | Notes |
| ------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAPI document type** | — | **URL** or **Content**. Default: URL |
| **URL** | When type is URL | Must start with `http://` or `https://` |
| **Content** | When type is Content | The OpenAPI/Swagger document as a JSON or YAML string. Not validated — invalid content fails silently in the viewer |
| **Authorization** | No | **none** (default), **Basic**, or **Api Key** — pre-fills credentials so Swagger UI can authorize **Try it out** requests automatically on load |
| **Login** / **Password** | When Authorization is Basic | Stored in the macro config |
| **Api Key** | When Authorization is Api Key | Stored in the macro config |
| **Validator URL** | No | Default: `https://validator.swagger.io/validator`. Clear it to disable the validation badge |
| **Layout** | No | Default: `BaseLayout` — the name of a Swagger UI plugin component to use as the top-level layout. Leave as is unless a custom plugin registers another layout |
| **Default Model Expand Depth** | No | Default: `1`. How many levels of a schema model are expanded by default; `-1` expands fully |
| **Filter** | No | Default: empty (disabled). When set, shows a filter box in the top bar pre-filled with this value |
| **Expansion** | No | `list` (default), `full`, or `none` — default expansion of tags and operations |
| **Model Rendering** | No | `example` (default) or `alpha` — which tab is active by default in the request/response body section |
| **Supported Submit Methods** | No | Multi-select of `get`, `put`, `post`, `delete`, `options`, `head`, `patch`, `trace`. Default: all selected. Removing a method hides **Try it out** for operations of that method only — it doesn't remove them from the list |
| **Display** | No | Checkboxes, all off by default — see below |
With **OpenAPI document type** set to **URL**, the form shows the **URL** field:
With it set to **Content**, the **URL** field is replaced by the **Content** text area:
### Display options
| Option | Default | Effect |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| **Display Operation Id** | Off | Shows the spec's `operationId` alongside each operation name |
| **Display Request Duration** | Off | Shows elapsed time after a **Try it out** request completes |
| **Show Extensions** | Off | Shows vendor extension (`x-`) fields on operations, parameters, responses, and schemas |
| **Show Common Extensions** | Off | Shows parameter validation constraints (`pattern`, `maxLength`, `minLength`, `maximum`, `minimum`) |
| **Request Snippets Enabled** | Off | Replaces the legacy curl snippet with the richer multi-language request snippet panel |
Fields left empty, or checkboxes left unchecked, aren't saved to the macro's config — Swagger UI falls back to its own built-in defaults for anything not explicitly set.
## Permissions
Anyone with edit access to a Confluence page can insert the macro and change its configuration. Page viewers without edit access only see the rendered output.