Aglio: API Documentation Tool That Has It All

Writing API documentation is an integral part of any web development process. Luckily, there are plenty of dedicated tools available to back you up. The downside of such abundance of tools is that it’s become difficult to find a really suitable one. For example, Markdown markup doesn’t always fit although it is considered to be one of the most popular approaches.

In this regard, JetRuby developers have decided to prepare a guide-review of a tool that we’ve been using for a while and which should help you write good and easy-to-maintain API documentation. The tool is called Aglio. You can see the whole list of tools here.

Briefly, Aglio is an API Blueprint rendering tool that prototypes and outputs static HTML pages. In its turn API Blueprint is a powerful Markdown-based API description language for prototyping and modelling new APIs. It can also be used to describe APIs that already exist.
Now it’s time we switched from theory to practice!

Setting up Aglio

What we are going to use:

  • A simple app with an API to output a list of all posts and information about their authors;
  • API documentation written in API Blueprint.

First, we install Aglio:

Then we run generator:

After that, it will create an html file based on the existing documentation.

Any customization options?

There are 5 default themes in Aglio. Further, Aglio provides you with two ways of displaying info: either in two or three columns. You can see the example below.

This the default theme looks like:

These are the themes that are also available: streak, flatly, slate, cyborg. To apply any of them you need to use --theme-variables

Moreover, Aglio allows for using your own styles:

To simplify working with documentation you can run a server for previewing (http://localhost:3000):

For generating documentation, we recommend using Atom and the plugins to work with API Blueprint: api-blueprint-preview and Linux-api-blueprint.

So why do we like Aglio after all?

  • Easy to get started thanks to Markdown.
  • You can store code and/or documentation in the same repository. Moreover, you can update, review and merge them synchronously.
  • Easy to get into API documentation because the unified structure. It also does great job in preventing mistakes like specifying the same response code for the same resource twice.
  • Once you’re familiar with the API Blueprint you can effortlessly create API documentation.
  • What you get on the output looks really nice. As we’ve mentioned, because the documentation structure is unified, users don’t have to spend a lot of time trying to make heads or tails of it.

But what about disadvantages? Here are things we want to be able to do with Aglio:

  • Store API documentation in one big file.
  • Divide documentation between multiple files right out of the box.
  • Reference arbitrary content to reduce duplication.
  • Define several various response/request examples for a method.

In addition, we think that response bodies should be able to have both a reference to a model and some text.

In Conclusion

The Internet is full of services that work with API Blueprint, you just have to choose the one that suits you the most. Aglio has worked for us, so you should also give it a try!
If you liked the article, share it your socials and leave your thoughts in the comments below!