Documentando sua API Rest com Swagger

Sem nos prendermos muito a definições e conceitos muito grande, o Swagger é um projeto para descrever a API REST, que mediante a leitura automatizada da estrutura da API, fornece uma documentação interativa e amigável, com informações sobre uma lista de todas as operações suportadas, parâmetros esperados e o valor que ele retorna.

Gosto de pensar que ele resolve duas coisas pra mim: quais são os recursos da minha aplicação e como testá-las? (galera, existe mil formas de resolver essas coisas… não é só o Swagger, blz!)

Agora chega de conversa e vamos iniciar criando nossa classe de configuração do Swagger! Eu sempre crio um package config nos meus projetos e curto muito usar o nome da classe sobre esse conceito, (o que é + pacote), dando um resultado de nome final de SwaggerConfig, mas isso é opcional, blz!

Não foi fornecido texto alternativo para esta imagem

Observe que anotação @Configuration identifica no Spring Framework que ela é uma classe de configuração, logo após, a anotação @EnableSwagger2 faz com que seja habilitado o Swagger no projeto.

Lá no seu pom.xml, você deve adicionar duas dependências, a primeira é do Swagger em si, na sequência é para importar a dependência da interface do Swagger, a parte visual mesmo.

Não foi fornecido texto alternativo para esta imagem
Não foi fornecido texto alternativo para esta imagem

Logo depois, de volta na sua classe SwaggerConfig, crie o método abaixo, vamos dar uma olhada nele.

Basicamente o “DocumentationType.SWAGGER_2” sinaliza a tipagem do documento como sendo Swagger 2, já no “.apis” observe que passamos um parâmetro que faz com que documente todas as classes anotadas com @RestController e em “.paths” passamos “any()” para capturar qualquer rota, ou seja, sem definição de uma rota específica.

Não foi fornecido texto alternativo para esta imagem

Feito! Rode seu projeto, acesse http://localhost:8080/swagger-ui.html (verifica se tá rodando na porta 8080.. ok! Mude conforme contexto)

Seu Swagger já está rodando… mas não acabou!

Não foi fornecido texto alternativo para esta imagem

Bem, como aprendizado inicial você já mandou super bem, mas na vida real, você não vai encontrar nenhuma aplicação sem segurança… (Eu gosto de pensar que não existe, mas vai saber.. rs!)

No caso da minha aplicação de exemplo, estou com o Spring Security implementado na aplicação, ou seja, bem provável que vá receber um unauthorized no acesso… veja só!

Não foi fornecido texto alternativo para esta imagem

Para que possamos acessar o Swagger, será preciso algumas configurações adicionais, começando pela classe ResourceServerConfig implementada, vamos declarar uma constante com vários endpoints e recursos de utilização do Swagger.

Não foi fornecido texto alternativo para esta imagem

Logo após vamos criar um método para disponibilizar o Swagger para todos, le voilà… temos nosso Swagger rodando, mas calma! Ainda não acabou… você não pode deixar a porteira do seu Swagger aberta, certo!!

Não foi fornecido texto alternativo para esta imagem

Pra ficar top (e seguro) temos que implementar o JWT em nosso Swagger.. bora lá!

Voltando para nossa classe SwaggerConfig vamos precisar implementar algumas modificações, de forma geral, são implementações de autorização e segurança, eu os coloquei em destaque no código, porém a explicação vai ficar para um próximo artigo de segurança… combinado! 😉

Não foi fornecido texto alternativo para esta imagem

Com essas implementações de segurança, teremos um Swagger rodando com segurança de aplicação nele… veja abaixo o detalhe dos cadeados a direita que não tinham antes dessa implementação, agora para acessar será preciso fornecer um token válido \o/.

Não foi fornecido texto alternativo para esta imagem

Esse é um assunto extenso, que envolve diversos conhecimentos do ecosistema Spring, mas fica aqui uma pitada de conhecimento compartilhado. Um Grande Abraço!!!

Leave a Reply

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *