Search code examples
swagger-uihugohugo-shortcodedocsy

Hugo Docsy SwaggerUI shortcode doesn't render the specs file

I'm trying to render an OAS file using Hugo Docsy SwaggerUI Shortcode but the rendered page doesn't contain the expected result.

Here is my rest-api.md file:

---
title: "REST API"
linkTitle: "REST API"
date: 2021-02-21
weight: 2
description: >
  REST API described using OpenAPI Specification.
---

{{< swaggerui src="http://localhost:1313/access.yaml" >}}

And here is the rendered page:

rendered page

As you can see, the HTML contains the following script that tries to render the OAS file:


  var resolveUrl = function () {
    var passedUrl = 'http:\/\/localhost:1313\/access.yaml';
    var baseUrl = '\/\/localhost:1313\/'.replace(/\/$/, '');
    if (passedUrl.startsWith('/')) {
      return baseUrl + passedUrl;
    }
    return passedUrl;
  };
  window.onload = function () {
    const ui = SwaggerUIBundle({
      url: resolveUrl(),
      dom_id: '#ohpen_swagger_ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ]
    });
    window.ui = ui;
  };

It is to be noted that http://localhost:1313/access.yaml resolves successfully to access.yaml file.

What prevents the OAS file to be rendered?

Solution

  • I have found my mistake. The type must be set to swagger in the front-matter of the page.

    The page must be as follows:

    ---
title: "REST API"
linkTitle: "REST API"
type: swagger
date: 2021-02-21
weight: 2
description: >
  REST API described using OpenAPI Specification.
---

{{< swaggerui src="http://localhost:1313/access.yaml" >}}

    The OAS file can be referenced using relative path /access.yaml in case it is served by Hugo as a static file.