[Lumen/Laravel] Como documentar uma API Rest com o Swagger

Olá!

Construir API`s tornou-se uma demanda comum nos últimos anos para desenvolvedores web. Vários frameworks apareceram com o objetivo de facilitar, organizar e padronizar o desenvolvimento dessas aplicações. Mas.. e a documentação?

Vou mostrar nesse post uma forma que venho utilizando nos projetos que atuo.

O Swagger

Este software vem me ajudando muito. Basicamente você define em um JSON todas as rotas da sua api junto com métodos, parâmetros, campos requeridos, tipos de resposta.

Depois de definir, basta apontar no SwaggerUI o seu JSON. O pessoal desenvolveu um exemplo de um petshop http://petstore.swagger.io/v2/swagger.json

Eles também desenvolveram um editor que ajuda a criar o seu arquivo swagger.json http://editor.swagger.io/

Bem, dependendo da API que você estiver criando, este arquivo ficará gigante (mesmo desmembrando em outros arquivos). Imagina a manutenção disso?

Criando o arquivo swagger.json com o PHP

Que tal utilizar annotations no seu código com informações da sua API e rodar um simples comando que gere o arquivo swagger.json ? É isso que a library zircote/swagger-php faz!

Vamos criar uma API super simples e documentá-la. Aqui vou utilizar o Lumen, mas pode ser utilizado da mesma forma com o Laravel.

Crie um projeto Lumen:

Acesse o diretório api-exemplo e instale o pacote swagger-php:

Aqui um exemplo de um arquivo routes.php com a rota GET /produtos declarada.

Para documentar, vamos adicionar algumas annotations no código:

Agora executamos o comando do swagger-php  para gerar o arquivo swagger.json

Captura de Tela 2016-04-01 às 15.39.43
$ vendor/bin/swagger app -o public/swagger.json

Após este comando , o arquivo swagger.json foi criado na pasta pública  public/swagger.json

Testando do SwaggerUI

Você pode clonar o SwaggerUI e executá-lo na sua máquina utilizando um http-server qualquer. Basta clonar o repositório https://github.com/swagger-api/swagger-ui

Templates do SwaggerUI

  • https://github.com/jensoleg/swagger-ui

Swagger_explorer