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.
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 is the default theme.
These are the themes that are also available: streak, flatly, slate, cyborg. To apply any of them you need to use
Moreover, Aglio allows for using your own styles:
To simplify working with documentation you can run a server for previewing (http://localhost:3000):
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.
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!