Swagger is a specification that allow you to describe in a standard way your API routes. An API description looks like this:

consumes:
  - application/json
produces:
  - application/json
paths:
  /fruits:
    get:
      summary: List all fruits
      responses:
        200:
          description: An array of fruits
          examples:
            application/json: >
                {
                    "fruits": [
                        {
                            "id": 1,
                            "name": "Cherry",
                            "price": 6.30,
                            "description": "Lovely red cherries",
                            "origin": [
                                "france"
                            ]
                        },
                        {
                            "id": 2,
                            "name": "Peach",
                            "price": 4.10,
                            "origin": [
                                "spain",
                                "italy"
                            ]
                        }
                    ]
                }

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 correct template.

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.