Uma das melhores decisões técnicas que tomei na minha carreira foi investir pesado nas arquiteturas baseadas em serviços. Meu primeiro post sobre isso data de 2011 e desde então esta decisão só se provou um acerto.
Uma das tarefas mais importantes, e chatas, é manter a documentação das APIs sempre atualizadas pois elas são consumidas por cada vez mais camadas: frontend, mobile, outros serviços e sistemas.
Existem várias ferramentas para esta tarefa, sendo uma das mais completas, e complexas, o Swagger, além de alguns serviços pagos. Estamos usando o Swagger em um grande projeto, mas eu estava a procura de algo mais simples para ser usado no Planrockr e encontrei o APIDOC.
Trata-se de um aplicativo escrito para o NodeJS que lê anotações nos seus códigos e gera uma documentação em HTML bem simples mas eficaz. Além das linguagens que usam o formato Javadoc Style ( C#, Go, Dart, Java, JavaScript, PHP, TypeScript) ele consegue gerar documentação em arquivos CoffeeScript, Elixir, Erlang, Perl, Python e Ruby.
Para instalar a ferramenta é necessário ter instalado o gerenciador de pacotes do NodeJS, o npm e rodar o comando:
npm install apidoc -g
No site oficial é possível ver todas as anotações disponíveis, mas abaixo um exemplo de uma documentação do Planrockr:
/**
* @api {post} /bitbucket/saveRepository Save a new repository
* @apiVersion 1.0.0
* @apiName SaveRepository
* @apiGroup Bitbucket
*
* @apiParam (parameters) {String} projectId Project's ID
* @apiParam (parameters) {String} repository[uuid] Repository's Id
* @apiParam (parameters) {String} repository[owner] Repository's Owner
* @apiParam (parameters) {String} repository[slug] Repository's Slug
*
* @apiError (406) InvalidParameters Invalid parameters
* @apiError (404) ProjectNotFound Project not found
* @apiError (406) RepositoryAlreadyUsed Repository already used
*
* @apiSuccess (201) {String} status Status
* @apiSuccess (201) {String} data Ok
* @apiSuccess (201) {Number} statusCode Status Code
*/
O próximo passo é criar na raiz do seu projeto um arquivo chamado apidoc.json com algumas configurações básicas:
{
"name": "Planrockr",
"version": "1.0.0",
"description": "Planrockr",
"title": "Planrockr API",
"url" : "http://app.planrockr.dev/rpc/v1"
}
E para gerar a documentação basta executar:
apidoc -c apidoc.json -i . -e backend/vendor -e planrockr-backend/frontend/bower_components -o ./apidoc
Para ver as opções do comando é só usar o
apidoc --help
Alguns exemplos da documentação gerada:
Além de ser bem bonita e fácil de acessar é possível incluir a sua geração em um script de commit, build ou deploy. E por suportar várias linguagens é fácil manter uma documentação unificada e gerada automaticamente.
O que você vem usando para esta tarefa? Se tiver outra sugestão por favor complemente aqui nos comentários.