Concrete Logo
Hamburger button

Documentando APIs com ApiDoc.js

  • Blog
  • 4 de Dezembro de 2014
Share
ApiDoc.js

ApiDoc.js

Existem várias formas de documentar as interfaces de uma API, 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 príncipio de que você vai documentar sua API em código.

Neste post vou apresentar uma ferramenta que esta sendo muito útil em meus projetos de API, ela é uma CLI (Command Line Interface) escrita em Node.js e ela 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:

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

Aviso: Neste post vou mostrar apenas utilizando o CLI padrão, mas caso você precise configurar o plugin grunt, veja esse link: https://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:

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:

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:

Se quiser testar se sua api esta funcionando, basta rodar o comando:

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

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 utiliza-se 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:

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:

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 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:

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

Documentação da API gerada pelo ApiDoc.js

Documentação da API gerada pelo ApiDoc.js

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: https://apidocjs.com
Github do apidoc-example: https://github.com/caio-ribeiro-pereira/apidoc-example