Documentação é um ponto essencial e chave para qualquer projeto de softwares eu costumo dizer que a documentação é o coração de qualquer projeto, afinal uma aplicação que está mal documentada ou com nenhum tipo de documentação pode dificultar o entendimento por parte da equipe e de usuários sobre o comportamento da mesma.
Portanto neste artigo iremos mostrar uma poderosa ferramenta que tem como intuito ajudar desenvolvedores nessa tarefa de criar boas documentações de suas APIs de forma rápida e automatizada.

O que é SWAGGER?

Swagger é um framework opensource composto por diversas ferramentas, que auxilia o desenvolvedor na descrição, no consumo e na visualização de uma API REST,no entanto para realizar tais tarefas o Swagger se utiliza de uma especificação chamada OPENAPI que define um padrão padronizado de uma requisição JSON.
Como já dissemos anteriormete o swagger é composto por diversas ferramentas mas as principais são:

• Swagger Editor - sua função principal é ajudar o desenvolvedor a definir uma estrutura de uma API no inicio de um projeto(https://editor.swagger.io/)

• Swagger Codegen - sua função principal é criar todo o “esqueleto” da API a partir de uma descrição em YAML.

• Swagger UI - sua função principal é criar uma documentação elegante,por meio de uma interface gráfica, onde usuários podem descrever suas APIs e realizar testes nas mesmas sem que haja qualquer tipo de dano aplicação em ambiente de produção.

Neste artigo vamos mostrar como integrar uma aplicação java utilizando o Swagger UI.

Adicionando a Lib SpringFox numa API com Spring Boot

Com a aplicação criada e com os endpoints funcionando,adicione no pom.xml essas duas dependências:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Com as dependências recém colocadas na aplicação chegou a hora de habilitar o swagger, para isto no pacote principal da aplicação dentro da classe Application(classe esta que dá o start na aplicação e inicializa todos os beans) ou se preferir você pode criar uma classe de configuração SwaggerConfig conforme podemos vê abaixo:

Neste método estamos definindo que nosso bean que chamamos de Docket terá acesso a todos os endpoints da aplicação, além disso criamos um método privado que retorna um objeto do tipo ApiInfo
que tem como objetivo criar informações customizadas acerca dos nossos endpoints.Com isso através de reflection a lib já consegue obter os endpoints que estão disponíveis na aplicação.
Para acessar o Swagger UI é necessário digitar(http://localhost:8080/swagger-ui.html) o resultado será semelhante ao da figura abaixo:

Personalizando Mensagens Globais:

Caso você precise personalizar todos os códigos de retorno que um endpoint retorne você precisará utilizar dentro do nosso bean Docket o método globalMessage recebendo como parâmetro um método http e uma lista de ResponseMessage conforme podemos ve abaixo(no meu caso eu fui definindo atributos final do tipo ResponseMessage e na chamada do globlaResponseMessage fui colocando esses atributos dentro de um array)

Utilizando Autenticação no Swagger

Caso sua aplicação utilize algum tipo de autenticação é necessário configurarmos no SpringFox, para isto utilizamos dois métodos o securityContext e SecurityScheme. No primeiro método defino o tipo de autenticação( se é ApiKey,BasichAuth,OAuth) e o segundo defino particularidades da autenticação.

No exemplo abaixo definimos uma autenticação do tipo ApiKey dentro do nosso bean Docket e definimos que o endpoint pedido deverá ter uma autenticação:

Após isso, rode novamente e ao acessar novamente a tela do Swagger-UI você verá no canto direito o botão Authorize conforme podemos vê na imagem abaixo:

Ao clicar nele ele pedirá que você informe seu token

Após informar seu token já será possível realizar consultas nos endpoints que exijam autenticação