Swagger is a specification that allow you to describe in a standard way your API routes. An API description looks like this:
As the description is standard there is a lot of tools to integrate and use a swagger description (for example to automatically create a client that consumes the API). An interesting one is Swagger UI a collection of HTML/CSS/JS files that generate a user friendly human readable documentation of your API. It can even allow readers to live test some routes!
As explained before I think that Jekyll is an excellent choice for a documentation. The problem is that there were nothing to render a swagger description within a Jekyll website (especially when using GitHub pages).
Not a problem! Swagger use YAML to describe an API and
Jekyll understand well YAML too, in it front matter (between
---) but also as
data file (in the
_data directory). Putting your swagger description into
your Jekyll website allows you to easily render it in your pages with the
To ease this integration, I have created a small project, jekyll-swagger to automatically render any Swagger description within Jekyll and this without plugin. It means that unlike other solution, it works on GitHub pages and stays very minimalist (no ruby or other generation hack).
Checkout the online demo for usage instructions and examples. Note that this is a base template, it can be to be very easily customized to match your style requirements.