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.

Parameter

Sett'ns

Enabl'n Link Warn'ns

Opt'n Front Matter Ye can use openapi.errorlevel t' control what should happen if a local OpenAPI specificat'n link can not 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 can not 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.

[openapi]
  errorlevel = 'warning'

openapi:
  errorlevel: warning

{
   "openapi": {
      "errorlevel": "warning"
   }
}

Load'n an External Version o' th' Swagger UI Library

Opt'n Front Matter Th' theme uses th' shipped Swagger UI library by default.

In case ye want do use a different version o' th' Swagger UI library but don’t want t' override th' shipped version, ye can set customOpenapiURL t' th' URL o' th' external Swagger UI library.

customOpenapiURL = 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'

customOpenapiURL: https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js

{
   "customOpenapiURL": "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
}

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 load'n th' Swagger UI library if no shortcode or codefence was used by sett'n openapi.force=true. If a shortcode or codefence was found, th' opt'n has no effect. This comes handy 'n case ye be us'n script'n t' render a spec.

[openapi]
  force = true

openapi:
  force: true

{
   "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 vari'ble 'n yer color variant stylesheet. This allows yer specs t' look pretty when th' user switches th' color variant.

Example

Us'n Local File

{{< openapi src="petstore.json" >}}