Documentação de projeto

Apigen – Documentando projetos de forma simples e rápida

O Apigen é uma ferramenta simples mas muito poderosa quando se fala em documentação de aplicações web. Ela é muito fácil de ser instalada e configurada, e é isso que você aprenderá nesse tutorial.

Alguns dizem que o Apigen serve apenas pra documentar APIs, mas não é verdade, ele pode documentar não só APIs como também sistemas web.

Instalando o Apigen

A instalação do Apigen pode ser feita de 3 maneiras: composer, .phar e apt install.

Vou mostrar como instalar via Composer que é a forma mais recomendada.

Para uma instalação global você deve utilizar o comando a seguir no terminal:

composer global require --dev apigen/apigen

Se quiser fazer a instalação apenas para um projeto específico, pode utilizar o seguinte comando:

composer require --dev apigen/apigen

Configurando o Apigen

Para configurar o Apigen para a geração da documentação vamos utilizar um arquivo de configuração com a extensão .neon. Esse é o padrão de arquivo de configuração do Apigen e vai permitir que você não precise escrever todos os parâmetros de configuração no terminal junto do comando de geração da documentação.

Na raiz da sua aplicação crie um arquivo chamado apigen.neon e adicione a ele o conteúdo a seguir:

Após criar o arquivo de configuração já possível gerar a documentação do projeto. Para isso vá até o terminal, acesse o diretório da aplicação e execute o comando a seguir. Esse comando vai fazer com que o Apigen localize o arquivo apigen.neon e assuma as configurações dele, gerando em seguida a documentação.

apigen generate

Após executar o comando o retorno no terminal deve ser o seguinte:

Scanning sources and parsing
Found 1 classes, 0 constants and 0 functions
Generating API documentation
100 % - Finished!

Veja que foi encontrada apenas uma classe, e está correto, pois a base de código utilizada para esse exemplo foi de uma instalação limpa do CodeIgniter 3.1.3, onde só existe a classe Welcome, dentro de application/controllers.

O resultado visual pode ser visto acessando o diretório /doc através do browser. No meu caso aqui ficou http://localhost/apigen_codeigniter/doc.

Exemplo de documentação com Apigen

Para documentar o seu código você fará uso do padrão de documentação do PHPDocumentor. Veja a seguir um exemplo da classe Welcome com alguns métodos documentados.

Se executar novamente o comando ‘apigen generate’ após atualizar os comentários do código conforme o exemplo acima, você terá um resultado visual semelhante à imagem abaixo:

Exemplo de documentação com Apigen

Viu como é fácil documentar seu projeto?!

Com comentários no próprio código-fonte e um comando no terminal você gera em poucos minutos toda a documentação do seu projeto, em HTML.

Bons estudos!