Elton Minetto

Gerando documentação de APIs

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:

apidoc1

apidoc2

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.

Powered by WPeMatico