Como usar o NelmioApiDocBundle no Symfony?

---

O que é o NelmioApiDocBundle e para que ele serve?

O NelmioApiDocBundle é uma ferramenta para o Symfony que gera a documentação de APIs em formato HTML ou JSON. Ele utiliza informações das anotações do framework para criar a documentação de uma forma automatizada, tornando mais fácil a integração com outras ferramentas que também trabalham com documentação de APIs.

Qual é a versão mais atual do NelmioApiDocBundle?

A versão mais atual do NelmioApiDocBundle é a 3.8.0. É importante verificar na documentação oficial qual é a versão compatível com a sua versão do Symfony.

Como instalar o NelmioApiDocBundle?

Para instalar o NelmioApiDocBundle, é necessário adicionar a dependência no arquivo composer.json do seu projeto:

"require": {

      "nelmio/api-doc-bundle": "^3.8",
 }

E executar o comando composer update para baixar a dependência.

Como configurar o NelmioApiDocBundle?

Para configurar o NelmioApiDocBundle, é necessário adicionar algumas configurações no arquivo de configuração do Symfony, app/config/config.yml:

nelmio_api_doc:

    documentation:
        info:
            title: Nome da API
            version: '1.0'
        securityDefinitions:
            Bearer:
                type: 'apiKey'
                name: 'Authorization'
                in: 'header'

No exemplo acima, foi adicionado o nome e versão da API, além de uma definição de segurança via token JWT.

Como utilizar as anotações do NelmioApiDocBundle?

O NelmioApiDocBundle utiliza anotações para gerar a documentação da API. Algumas das anotações mais utilizadas são:

/**

* @SWGGet(
*     path="/api/path",
*     summary="Descrição resumida da rota.",
*     @SWGResponse(response="200", description="Descrição da resposta.", @SWGSchema(type="array",
*                            @SWGItems(ref="#/definitions/class")))
* )
*/

No exemplo acima, a anotação @SWGGet indica que a rota é do tipo GET, o path indica o caminho da rota, o summary é uma descrição resumida da rota e o @SWGResponse é a definição da resposta da rota.

Como gerar a documentação da API?

Para gerar a documentação da API em formato HTML, é necessário executar o comando php bin/console nelmio:api-doc:dump –no-interaction –no-debug no terminal do Symfony. A documentação será gerada dentro da pasta public/doc/api.

Como acessar a documentação da API gerada?

A documentação gerada está acessível no endereço http://localhost/doc/api. É possível alterar o endereço no arquivo de configuração do NelmioApiDocBundle.

Como adicionar descrições mais detalhadas na documentação?

Para adicionar descrições mais detalhadas na documentação, é possível utilizar outras anotações do NelmioApiDocBundle, como @SWGParameter e @SWGDefinition. A anotação @SWGParameter permite definir o tipo e a descrição de um parâmetro e a anotação @SWGDefinition permite definir o tipo e a descrição de um objeto.

Como documentar as respostas de uma rota que pode retornar mais de um tipo de resposta?

Para documentar as respostas de uma rota que pode retornar mais de um tipo de resposta, é necessário utilizar a anotação @SWGResponse com vários parâmetros com diferentes valores de response, como no exemplo abaixo:

* @SWGResponse(

*     response=200,
*     description="OK",
*     @SWGSchema(type="object",
*                @SWGProperty(property="status", type="integer"),
*                @SWGProperty(property="data", type="array",
*                              @SWGItems(ref="#/definitions/class")))
* )
* @SWGResponse(
*     response=404,
*     description="Not Found"
* )

Como testar a API?

Para testar a API, é possível utilizar ferramentas como Postman ou curl. É importante verificar se a resposta da API está de acordo com a documentação gerada pelo NelmioApiDocBundle.

Como customizar a documentação gerada?

Para customizar a documentação gerada, é possível utilizar templates Twig fornecidos pelo NelmioApiDocBundle ou criar os seus próprios templates. É possível também definir a ordem em que os endpoints serão apresentados na documentação através das configurações do NelmioApiDocBundle.

---