Creating REST API docs with Aglio

API Blueprint describes itself as a powerful high-level API description language for web APIs. It’s a opensource project with MIT license that focuses on collaboration and encourages better API designs through abstraction.

For any API-first design, the main goal is to design the API on not focusing on the backend implementation behaviour. Designing your API first is like settling a contract before it is developed, which leads to better designs.

So the API Blueprint is like a design language and there are lots of tools available to design the same thing following a specification.

Developing with Aglio

Aglio is an API Blueprint renderer with theme support that outputs static HTML. It compiles a markdown file with API Blueprint standards.

Let’s start using it.

Installing

Let’s create a folder aglio-test to start tinkering with our API design process and create a package.json file to put down the dependencies.

{
  "name": "aglio-test",
  "version": "1.0.0",
  "description": "Test API with Aglio",
  "scripts": {
    "dev": "aglio --theme-full-width --theme-template triple --theme-variables slate -i docs.md -s",
    "build": "aglio --theme-full-width --theme-template triple --theme-variables slate -i docs.md -o index.html"
  },
  "author": "Tareq Hasan <[email protected]",
  "license": "MIT",
  "dependencies": {
    "aglio": "^2.3.0"
  }
}

Here I’m using two npm scripts to parse and generate the documentation. These two are just few ready-made commanline parameters to get started by. It actually instructs Aglio that what theme we want to use and which file to parse.

There are few themes available for use.

After you’ve created the package.json following the one above, let’s install the dependencies:

npm install

All the dependencies will be installed.

Creating Docs

As described in the npm scripts, we are using a docs.md file to write all our docs. Aglio will turn the markdown into pretty API docs file.

The standard file starts with a FORMAT metadata identifying the version of API Blueprint and the HOST as your API endpoint URL.

FORMAT: 1A
HOST: https://api.domain.com/v1

I’m not going into more details and docs for API Blueprint as it’s already available in their site.

Developing

While developing with documentation, you can watch for changes and aglio will build the preview on-the-fly. Just run:

npm run dev

It’ll open a local server and will monitor the changes. Once you do any changes, will be reflected on the browser.

Building

After you finish developing, you can run:

npm run build

Aglio will parse the docs.md file and generate a index.html as specified in the npm scripts. You can deploy the file in a domain somewhere to publish your API documentation.

Enjoy!