Documentando minha API #1 — API Blueprint + Aglio

Mexer num projeto cuja API não tem documentação é um sofrimento… ter que vasculhar no código do projetos os endpoints e entender o que é possível fazer com cada um deles é um trabalho desnecessário, e seria resolvido de forma simples com uma bendita documentação :(.

Já diz a frase:

Uma API documentada é uma API feliz

Eis que chega a minha hora de fazer um projeto novo, e não posso cair na mesma mancada de deixar o código ser a fonte de entendimento da API.

Como especificação para a construção dessa documentação, optei pela API Blueprint. Criada pela Apiary(Oracle), tem a vantagem de ser escrita utilizando Markdown, facilitando a leitura.

Começando

Seguindo o padrão da API Blueprint, podemos escrever nossa documentação em Markdown ou com a extensão .apib. Optei pela segunda, já que é possível encontrar extensões para meu editor de texto.

O exemplo acima faz o seguinte:

• Seta a url da api para http://api.meninogaimeiro.com.br;
• Cria um grupo de rotas chamada games;
• Cria um grupo de rotas Games /games. Nesse meu exemplo ficou repetido, mas poderia existir junto com essa rota o Platforms /games/platforms;
• Crio uma request informando seus headers e seus atributos;
• Crio uma response informando seus status codes e seus payloads

Para ver como essa documentação é renderizada usando o Apiary, clique aqui.

Gerando a documentação

A API Blueprint é apenas uma especificação, não uma tecnologia. Para gerar uma documentação em meu projeto Node, acabei por utilizar a engine Aglio, que será responsável por interpretar os arquivos nesse formato e renderizar a documentação formatada.

Para isso, faça:

• npm install -g aglio
• aglio -i api.apib — theme-template triple -s

Esse último comando lerá o arquivo api.apib, gerando um template de 3 colunas em um servidor.

Eis que o resultado será algo como mostrado na imagem abaixo:

Pronto! Com isso já posso dar continuidade na documentação da API :).