Uma das coisas mais legais do Apigility é a capacidade de gerar documentação de API usando uma interface de usuário bem simples. Ela é gerada em formato HTML e, se preferir, em formato Swagger, e aparece no Apigility na barra superior, no menu “Docs API” (Figura 1, usando Apigility 1.0.0beta1).

 

Para gerar a documentação da API, é necessário inserir algumas descrições antes. Todas as informações para editar estão na aba “Documentação” em cada serviço REST ou RPC (Figura 2).

 

É possível especificar uma descrição da ação para cada serviço e cada método HTTP. No caso de serviços RESTful, você também pode especificar informações diferentes para uma Entity e uma Collection. Uma característica interessante da documentação da API é a capacidade de gerar a especificação Response Body a partir da configuração, usando o botão “gerar a partir de configuração” (Figura 3).

 

Esse botão lê a configuração da API e propõe uma resposta JSON com base nos campos especificados (os campos estão documentados na aba Campos de cada serviço REST e RPC). É claro que você pode editar o corpo da resposta alterando a saída, caso seja necessário.

Depois de adicionar algumas descrições da API, você pode ir ao menu “Docs API” e exibir a documentação da API (no nosso caso, a versão 1, Figura 4).

 

Você vai ver toda a documentação da API no formato HTML, usando o template Bootstrap 3.

É possível expandir e reduzir as informações em cada método HTTP clicando no nome. Toda a documentação de API está exposta na URL base /apigility/documentation.

Como instalar o adaptador Swagger

Para ativar o adaptador Swagger para a documentação da API, você precisa adicionar a seguinte dependência no arquivo composer.json (no campo exigido):

"zfcampus/zf-apigility-documentation-swagger": "~1.0-dev"

e executar o comando composer update.

Depois da instalação do zf-apigility-documentation-swagger, você precisa ativar esse módulo no arquivo config/application.config.php. É preciso editar o arquivo de configuração e adicionar a seguinte linha após ‘ZF\Apigility\Documentation’ :

'ZF\Apigility\Documentation\Swagger',

Agora é possível acessar a documentação Swagger a partir da tela de boas-vindas, clicando no botão Swagger API documentation, ou indo diretamente até a URL /apigility/swagger.

Para mostrar o render do Swagger UI, você precisa selecionar a versão do serviço de API. Você vai ver uma página web como a mostrada na Figura 5 (usando Swagger UI).

 

Personalizando o módulo de documentação da API

A função documentação da API é oferecida pelo Apigility utilizando o módulo zf-apigility-documentation, escrito em Zend Framework 2. Esse módulo fornece um modelo de objeto de todas as informações de documentação capturadas, incluindo:

• Todas as APIs disponíveis
• Todos os serviços disponíveis em cada API
• Todas as operações disponíveis em cada API
• Todos os cabeçalhos Accept e Content-Type requeridos/esperados na requisição, e o cabeçalho Content-Type esperado na resposta, para cada operação disponível na API
• Todos os campos configurados para cada serviço

Além disso, ele fornece um endpoint MVC configurável para a devolução da documentação.

• a documentação será entregue, por padrão, em uma estrutura JSON serializada
• os usuários finais podem configurar formatos alternativos/adicionais via conteúdo de negociação

Se quiser personalizar o formato da sua documentação de API, você pode dar uma olhada no código-fonte do módulo de zf-apigility-documentation-swagger. Basicamente, você precisa criar uma rota personalizada para o seu formato (veja o Swagger module.config.php) e utilizar o ZF\Apigility\Documentation\ApiFactory para acessar os dados para os serviços de documentação da API. Para o view ser implementado, é precis gerenciar uma list views e um show view, só isso!

Todos os formatos de documentação da API são conduzidos pela negociação de conteúdo (usando o módulo zf-content-negotiation). Por exemplo, para pegar os dados de documentação da API no formato Swagger, você pode utilizar a negociação de conteúdo “application/vnd.swagger+json”.

Por exemplo, se você quer recuperar dados da documentação da API no formato JSON, você pode usar a seguinte solicitação (usando HTTPie):

http GET http://localhost:8888/apigility/documentation[/api]/[service] 'Accept:application/json'

onde [api] é o nome da API e [service] é o nome do serviço REST ou RPC. Para obter o mesmo resultado no formato Swagger, você pode utilizar a seguinte solicitação:

http GET http://localhost:8888/apigility/documentation/[api]/[service] 'Accept:application/vnd.swagger+json'

***

Artigo traduzido pela Redação iMasters com autorização do autor. Publicado originalmente em http://www.zimuel.it/documenting-apis-using-apigility/