OpenAPI

The openapi shortcode displays your OpenAPI / Swagger specifications using the 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 you want to print out (or generate a PDF) from your OpenAPI documentation, don’t initiate printing directly from the page because the elements are optimized for interactive usage in a browser.

Instead, open the print preview in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.

Parameter

Settings

Enabling Link Warnings

Option Front Matter You can use openapi.errorlevel to control what should happen if a local OpenAPI specification link can not be resolved to a resource.

If not set or empty, any unresolved link is written as given into the resulting output. If set to warning the same happens and an additional warning is printed in the built console. If set to error an error message is printed and the build is aborted.

Please note that this can not resolve files inside of your static directory. The file must be a resource of the page or the site.

Link warnings are also available for images & links and the include shortcode.

[openapi]
  errorlevel = 'warning'

openapi:
  errorlevel: warning

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

Loading an External Version of the Swagger UI Library

Option Front Matter The theme uses the shipped Swagger UI library by default.

In case you want do use a different version of the Swagger UI library but don’t want to override the shipped version, you can set customOpenapiURL to the URL of the 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 Loading of the Swagger UI Library

Option Front Matter The Swagger UI library will be loaded if the page contains an openapi shortcode or codefence.

You can force loading the Swagger UI library if no shortcode or codefence was used by setting openapi.force=true. If a shortcode or codefence was found, the option has no effect. This comes handy in case you are using scripting to render a spec.

[openapi]
  force = true

openapi:
  force: true

{
   "openapi": {
      "force": true
   }
}

Setting a Specific Swagger UI Theme

The recommended way to configure your Swagger UI theme is to set the default value using the --OPENAPI-theme variable in your color variant stylesheet. This allows your specs to look pretty when the user switches the color variant.

Example

Using Local File

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