OpenAPI
Full API reference rendered from an OpenAPI or Swagger spec, offline and theme-aware.
The openapi shortcode renders an OpenAPI 3.x (or Swagger 2) spec as a browsable API reference using a vendored Redoc bundle. There is no CDN dependency, so it works in air-gapped deployments. The bundle loads only on pages that use the shortcode and the reference re-renders when the theme switches.
File location
Where you place the spec file determines how it is loaded.
| Path style | Where the file lives | How it is loaded |
|---|---|---|
api.yaml (no leading /) |
Next to the page’s index.md as a page bundle resource |
Parsed at build time, embedded inline, works on private sites |
/path/to/api.yaml (leading /) |
In assets/ at that path |
Parsed at build time, embedded inline, works on private sites |
| Fallback (file not found in bundle or assets) | In static/ at that path |
Fetched at runtime, public sites only |
Build-time embedding parses the YAML or JSON spec and writes it directly into the HTML as JSON. No HTTP request is made when the reader opens the page, so the embed works on private GitLab Pages and any other auth-gated host.
Usage
{{< openapi "api.yaml" >}}Or with an absolute path from assets/:
{{< openapi "/docs/specs/api.yaml" >}}Live demo
The spec file for this demo lives at exampleSite/assets/docs/specs/sample-api.yaml in the theme repository and is embedded inline at build time.
{{< openapi "/docs/specs/sample-api.yaml" >}}Parameters
| Parameter | Description |
|---|---|
| 1st positional | Path to the .yaml or .json spec file. Relative paths resolve as page bundle resources. Absolute paths (leading /) resolve from assets/. |
Notes
- The Redoc bundle is vendored inside the theme. No internet connection is needed at build time or runtime.
- The reference respects the active color theme: primary color, text and sidebar colors all follow the theme palette.
- Interactive embeds are replaced with a static note in the printable handbook.