Existem várias formas de documentar as interfaces de uma API, mas até hoje não existe uma maneira padrão, ou seja, você pode documentar usando um Word ou Excel, utilizar ferramentas online ou simplesmente comentar seu código de forma que seja possível utilizar um interpretador que gere uma documentação estruturada para sua API. Esta última opção agrada (e muitos!) os desenvolvedores, pois tudo parte do princípio de que você vai documentar sua API em código.

Neste artigo vou apresentar uma ferramenta muito útil em meus projetos de API. Ela é uma CLI (Command Line Interface) escrita em Node.js e gera uma documentação bem amigável para APIs. Seu nome é ApiDoc.js, e ela não só gera documentação em código JavaScript, como também ela reconhece comentários em código Erlang, PHP, Java, CoffeScript, Ruby, Python e Perl.

Instalando ApiDoc.js

Para instalar seu CLI basta rodar o comando:

npm install apidoc -g

E caso você precise usá-lo integrado com o Grunt, ele também possui um plugin instalável via comando:

npm install grunt-apidoc --save-dev

Aviso: Neste artigo vou demostrar apenas utilizando o CLI padrão, mas caso você precise configurar o plugin Grunt, veja esse link: http://apidocjs.com/#grunt-module.

Criando uma API de exemplo

Para começar a brincadeira, primeiro vamos criar uma simples API, utilizando o Node.js com framework Express. Para isso, vamos criar o projeto seguindo os comandos abaixo:

mkdir apidoc-example
cd apidoc-example
npm init

Obs.: Fique a vontade para responder o que quiser no questionário do comando npm init; o importante é gerar o package.json no final deste comando.

Depois de criar o projeto, instale como dependência o módulo Express:

npm install express --save

Com o setup do projeto finalizado, mãos a obra! Como código de exemplo, a nossa API será criada com apenas dois endpoints inúteis (um para o método GET e outro para o método POST), sem funcionalidade real alguma, mas que servirá como base para criarmos os comentários para gerar a documentação da API. Para isso, crie o código app.js com o código abaixo:

var express = require("express");
var app = express();
 
app.use(express.static("public"));
 
app.get("/signin", function(req, res) {
res.json({status: "Você esta logado!"});
});
 
app.post("/signup", function(req, res) {
res.json({status: "Cadastrado!"});
});
 
app.listen(3000, function() {
console.log("Api up and running!");
});

Se quiser testar se sua API está funcionando, basta rodar o comando:

node app.js

Em seguida, abra seu browser e acesse o endereço http://localhost:3000/signin. Se estiver funcionando, a sua API vai retornar no browser essa resposta:

{status: "Você está logado!"}

Documentando a API

Para documentar com ApiDoc.js é muito simples: basta comentar seu código-fonte (preferencialmente acima de cada implementação de endpoint) utilizando as funções desse framework que geralmente utiliz o pré-fixo "@api". Veja abaixo como a nossa API (o código app.js) após documentá-la com comentários do ApiDoc.js:

var express = require("express");
var app = express();
 
app.use(express.static("public"));
 
/**
 * @api {get} /signin Singin
 * @apiGroup Sistema
 *
 * @apiSuccess {String} status Mensagem de acesso autorizado
 * 
 * @apiSuccessExample {json} Sucesso
 *    HTTP/1.1 200 OK
 *    {
 *      "status": "Logado!"
 *    }
 *
 */
app.get("/signin", function(req, res) {
  res.json({status: "Logado!"});
});
 
/**
 * @api {post} /signup Signup
 * @apiGroup Sistema
 *
 * @apiSuccess {String} status Mensagem de cadastro efetuado
 * 
 * @apiSuccessExample {json} Sucesso
 *    HTTP/1.1 200 OK
 *    {
 *      "status": "Cadastrado!"
 *    }
 *
 */
app.post("/signup", function(req, res) {
  res.json({status: "Cadastrado!"});
});

app.listen(3000, function() {
 console.log("Api up and running!");
});

Agora que temos nossa API documentada em código-fonte, vamos gerar uma documentação em formato HTML para disponibilizar uma documentação decentemente formatada e bem estruturada. Para isso, apenas rode o comando:

apidoc -f app.js -o public/apidoc

A flag -f ou –file-filter espera como argumento um arquivo ou uma expressão regular para capturar vários arquivos que contenham códigos com comentários interpretáveis pelo ApiDoc.js e a flag -o ou –output serve apenas para indicar o diretório em que será gerado a documentação da API.

Se você deseja apenas informar um diretório que contém códigos interpretáveis pelo ApiDoc.js, utilize a flag -i ou –input, fazendo por exemplo esse comando:

apidoc -i ./routes -o public/apidoc

Para visualizar a documentação, inicie sua api com o comando node app.js e acesse em seu browser o endereço: http://localhost:3000/apidoc. No final, você terá uma página com layout bem bacana e estruturado o suficiente para apresentar uma documentação para sua API, semelhante à imagem abaixo:

Este foi apenas um pequeno exemplo de como documentar uma API com ApiDoc.js. Recomendo que você leia sua documentação para aprender a fundo como configurar e como utilizar outros recursos de documentação de API.

Site oficial: http://apidocjs.com
Github do apidoc-example: https://github.com/caio-ribeiro-pereira/apidoc-example