Skip to main content

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.

A specification that is a resource of your page or site is found by the search. A specification given by URL is loaded by the browser of your reader and is not.

Parameters

Name Default Notes
src <empty> The path to the to the OpenAPI specification resource or URL to be used. Resource paths adhere to Hugo’s logical path.
lang <empty> The language code used for the reading direction of the Swagger UI and for the texts the theme adds to it, like Expand all and Collapse all. This must be one of the languages configured for your site. If not set, the language of the page is used.

Settings

Option Front Matter You can use openapi.errorlevel to control what should happen if a local OpenAPI specification link cannot 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 cannot 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.

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

Using a Different Version of the Swagger UI Library

The theme uses the shipped Swagger UI library by default.

In case you want to use a different version of the Swagger UI library, store its files as assets/js/swagger-ui/swagger-ui-bundle.js, assets/js/swagger-ui/swagger-ui-standalone-preset.js and assets/css/swagger-ui/swagger-ui.css in your site. They replace the shipped version.

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.

​
[params]
  [params.openapi]
    force = true
params:
  openapi:
    force: true
{
   "params": {
      "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 and OPENAPI-CODE-theme variable in your color variant stylesheet. This allows your specs to look pretty when the user switches the color variant.

The theme uses Swaggers theming support. For --OPENAPI-theme the only allowed values are light or dark. For --OPENAPI-CODE-theme the allowed values are agate, arta, monokai, nord, obsidian, tomorrow-night, idea.

Example

Using Local File

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