Oops... your message was not sent

Your message has been successfully sent

Jetruby Blog
Hire Us
Featured Technical Stories Based On Our Experience

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. However, such abundance of tools makes it hard to find a really suitable one. For example, Markdown markup may not always fit although it is considered to be one of the most commonly used approaches.

That’s why JetRuby developers have prepared a guide-review of a tool that should help you write good and easy-to-maintain API documentation called Aglio. You can see the whole list of tools here.

aglio api blueprint

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:

api documentation tool

Then we run generator:

running 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 is the default theme.
aglio themes
aglio themes

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.

Although Aglio has quite a lot of advantages, there are still things we would like to improve:

  • Storing API documentation in one big file. Further, splitting the documentation across multiple files doesn’t work out of the box.
  • Being able to reference arbitrary content to reduce duplication would be great.
  • Have an ability to define several various response/request examples for a method.
  • Response bodies must be able to contain 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 most suitable one. Since Aglio has worked for us, you should also give it a try!
If you liked the article, share it your socials and write your thoughts in the comments below!

This post created by
Web Development Department
Professional website designing and development.
New Articles