New OpenAPI Specification Shortcode for Hugo
I’ve hacked together a quick experiment that allows you to embed OpenAPI Spec inside a Hugo site.
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. [with the migration away from Hugo I've taken this down but you can still see the code here.]
The way I got this to work is I created a Hugo Shortcode which I call like this:
{{< oai-spec url="http://petstore.swagger.io/v2/swagger.json" 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.
