Como documentar uma API no Symfony
Hoje quero trazer a vocês uma forma de fazer a documentação de sua API Symfony sem muito esforço!
Afinal, documentação é uma parte super importante para o crescimento continuo de sistemas e empresas, então pensando nisso fiquei pesquisando formas de facilitar a minha vida e a de vocês com relação a isso, e testei varias hipóteses, para identificar qual seria o melhor para o meu contexto, segue algumas das opções vista:
Bom, explicando melhor o meu problema:
Já existe uma API em Symfony, já existe varias rotas não documentadas e já estava em produção, sem falar do quesito tempo a qual nunca tive para documentar essas rotas anonimas, mais precisamos de uma documentação para conseguir passar para frente, pois o sistema esta crescendo e suas funcionalidades poderiam ser reutilizadas em outros sistemas.
Vocês se identificam com algo acima ? pois é complicado, mais o NelmioApiDocBundle descomplicou tudo para nós :)
Então vou mostrar como foi simples trazer o minimo de documentação em minha API já existente utilizando essa ótima lib “NelmioApiDocBundle”.
Primeiro passo instalação da lib:
composer require nelmio/api-doc-bundle:^3.0Importante falar que caso não esteja utilizando annotations precisa também instalar pois será delas que iremos configurar nossa documentação.
Durante a instalação será perguntado se deseja incluir já os arquivos de configurações da lib digite “y” e segue o fluxo.
Com a lib já configurada você deve se deparar com dois novos arquivos em sua config:
- config/routes/nelmio_api_doc.yaml
- config/packages/nelmio_api_doc.yaml
Para habilitar a interface do NelmioApiDocBundle vamos descomentar a linha 9 até a linha 12 do arquivo config/routes/nelmio_api_doc.yaml, ficando assim:
Legal, com isso na teoria já poderíamos acessar o endereço api/doc e ver a interface:
Ops… não saiu como esperado ? bom esse erro é só porque ainda não foi instalado o twig e assets, então para correção dessas dependências caso você ainda não tenha instalado basta executar os seguinte comando:
composer require twig assetApós instalação das dependências acesse a rota novamente e terá uma tela funcional:
Mas pera, cade as minhas demais rotas ? bom amigos é um seguinte o essa lib vem por default configurada para pegar tudo que contenha o prefixo /api lá no arquivo config/packages/nelmio_api_doc.yaml e caso suas rotas tenham outro prefixo ou não tenha prefixo veja como ajustar, no meu caso eu deixei sem prefixo, então ajuste o path_patterns com essa expressão:
- ^/(?!_error/.*|api/doc$)
Com esse ajuste, terá esse resultado:
Ai sim em, agora o bagulho ta loko !
Talvez vocês tenham reparado que algumas rotas estão duplicadas exemplo a minha rota auth/login na verdade só existe uma, mas a documentação achou varias rotas /auth/login por que ? simples, porque a rota não foi declarada por qual método ela atende sendo assim por default essa rota vai atender todos os métodos “GET, POST, PUT, DELETE…”, a correção é bem simples, basta adicionar o parâmetro “methods” em sua rota e seu respectivo valor:
Agora veja o resultado, veja o resultado:
Bom só com isso já conseguimos ter uma API documentada, mas espera podemos melhorar ainda mais isso ai…
Que tal criar grupos de dados exemplo: Authentication, Users e Products? veja como é simples, basta adicionar @SWG\Tag(name=”Group Name”)
Legal galera acredito que terminamos por aqui, claro que da para ir mais fundo nessa documentação mais ai deixo a você como lição de casa como configurar os demais parâmetros ou modelos de resposta.
Segue o link do projeto utilizado aqui: https://github.com/everaldofilho/symfony-api-doc
Link da documentação oficial do Symfony:
https://symfony.com/doc/3.x/bundles/NelmioApiDocBundle/index.html
Até pessoal :-)
