Jeremy Brown

April 28, 2021

New OpenAPI Specification Shortcode for Hugo

Originally published on the 13th of July 2016.
One of the things I’ve been meaning to try for a while is to experiment with combining Open API Spec (formerly known as Swagger Spec) and static websites. So I’ve hacked together a quick experiment that allows you to embed OpenAPI Spec inside a Hugo site.

You can see an example of this in action here.

The way I got this to work is I created a Hugo Shortcode which I call like this:

{{< oai-spec url="" api_key="special-key" >}}

The shortcode embeds Swagger UI as a iframe and renders the OpenAPI Spec from the url you’ve passed in.

The full source of my hack is on GitHub as hugo-openapispec-shortcode.

I’m quite happy about how this turned out for a simple proof of concept, however if I was building this out a bit further or wanted to document an API properly I might consider writing a new template for Hugo that pulled the OpenAPI Spec from the Hugo data directory and render it using HTML/CSS templates, I think this approach might produce quite an awesome statically generated API docs site.