I'm on the hunt for new ways to deploy attractive, interactive API documentation, from machine readable API definition formats like Swagger and API Blueprint. I am advocating for the development of new approaches to deploy UI documentation, and part of this showcasing what I find along the way.
In the spotlight today is Aglio, which they describe as:
An API Blueprint renderer that supports multiple themes and outputs static HTML that can be served by any web host. API Blueprint is a Markdown-based document format that lets you write API descriptions and documentation in a simple and straightforward way.
Aglio is significant because it is driven from the machine readable format API Blueprint, and produces static HTML that can be served up anywhere, specifically on Github or Amazon S3 deployed using Jekyll. Additionally it just makes your document simple, easy to follow, and just damn sexy.
I’d love to see a Swagger generated version of Aglio, allowing you to deploy the attractive API documentation from both Swagger or API Blueprint. If more API documentation looked like Aglio, I would be a seriously happy camper.
