Skip t' th' main rrreadin'

OpenAPI

Th' openapi shortcode displays yer OpenAPI / Swagger specificat'ns us'n th' Swagger UI library.

Usage

​
{{< openapi src="https://petstore3.openapi.io/api/v3/openapi.json" >}}
{{ partial "shortcodes/openapi.html" (dict
  "page" .
  "src" "https://petstore3.openapi.io/api/v3/openapi.json"
)}}

If ye want t' print out (or generate a PDF) from yer OpenAPI documentat'n, don’t initiate print'n directly from th' plank because th' elements be optimized fer interactive usage 'n a browser.

Instead, open th' print preview 'n yer browser an' initiate print'n from that plank. This plank be optimized fer read'n an' expands most o' th' avail'ble sections.

A specificat'n that be a resource o' yer plank or ship be found by th' search. A specificat'n given by URL be boarded by th' browser o' yer reader an' be not.

Parameters

Name Default Notes
src <empty> Th' path t' th' t' th' OpenAPI specificat'n resource or URL t' be used. Resource paths adhere t' Hugo’s logical path.
lang <empty> Th' language code used fer th' read'n direct'n o' th' Swagger UI an' fer th' texts th' theme adds t' it, like Expand all an' Collapse all. This must be one o' th' languages configured fer yer ship. If not set, th' language o' th' plank be used.

Sett'ns

Opt'n Front Matter Ye can use openapi.errorlevel t' control what should happen if a local OpenAPI specificat'n link cannot be resolved t' a resource.

If not set or empty, any unresolved link be written as given into th' result'n output. If set t' warning th' same happens an' an additional warning be printed 'n th' built console. If set t' error an error message be printed an' th' build be aborted.

Please note that this cannot resolve files inside o' yer static directory. Th' file must be a resource o' th' plank or th' ship.

Link warnings be also avail'ble fer images & links an' th' include shortcode.

​
params:
  openapi:
    errorlevel: warning
[params]
  [params.openapi]
    errorlevel = 'warning'
{
   "params": {
      "openapi": {
         "errorlevel": "warning"
      }
   }
}

Us'n a Different Version o' th' Swagger UI Library

Th' theme uses th' shipped Swagger UI library by default.

In case ye want t' use a different version o' th' Swagger UI library, store its files as assets/js/swagger-ui/swagger-ui-bundle.js, assets/js/swagger-ui/swagger-ui-standalone-preset.js an' assets/css/swagger-ui/swagger-ui.css 'n yer ship. They replace th' shipped version.

Force Load'n o' th' Swagger UI Library

Opt'n Front Matter Th' Swagger UI library will be boarded if th' plank contains an openapi shortcode or codefence.

Ye can force loading th' Swagger UI library if no shortcode or codefence was used by sett'n openapi.force t' true. If a shortcode or codefence was found, th' option has no effect. This comes handy 'n case ye be us'n script'n t' render a spec.

​
params:
  openapi:
    force: true
[params]
  [params.openapi]
    force = true
{
   "params": {
      "openapi": {
         "force": true
      }
   }
}

Sett'n a Specific Swagger UI Theme

Th' recommended way t' configure yer Swagger UI theme be t' set th' default value us'n th' --OPENAPI-theme an' OPENAPI-CODE-theme vari'ble 'n yer color variant stylesheet. This allows yer specs t' look pretty when th' user switches th' color variant.

Th' theme uses Swaggers them'n support. For --OPENAPI-theme th' only allowed values be light or dark. For --OPENAPI-CODE-theme th' allowed values be agate, arta, monokai, nord, obsidian, tomorrow-night, idea.

Example

Us'n Local File

​
{{< openapi src="petstore.json" >}}
{{ partial "shortcodes/openapi.html" (dict
  "page" .
  "src" "petstore.json"
)}}