Documentando suas API com Swagger usando SpringFox

Setup Inicial

Vamos criar um API Rest para avaliação de livros, que será compatível com nossa API de livros criada nos tutoriais do nosso primeiro projeto Rest em SpringBoot.

Precisaremos criar um novo projeto no maven, o qual usaremos para configurar e codificar a nossa API.

Poderíamos criar o projeto do maven via IDE (Eclipse, IntelliJ, NetBeans e etc..), ou via linha de comando como o exemplo abaixo:

Por ambos os métodos, teríamos de remover as classes desnecessárias e fazer as configurações das dependências.

Mas nesse tutorial, vamos utilizar a ferramenta Spring Initializr que auxilia muito na geração de projetos SpringBoot, reduzindo muito o nosso tempo de bootstrap. Vamos acessá-lo em:

Teremos acesso uma página simples e bem clara:

Digite o nome do grupo:

Digite o nome do artefato:

Selecione nas dependências, a Web:

Selecione JPA:

E clique em Generate Project.

O Navegador fará o download de um arquivo compactado contendo um projeto maven que poderá ser importado na sua IDE.

Vejamos o pom.xml gerado automaticamente pelo site:

Observe que o projeto já contém as dependencias necessária para a construção e execução de testes unitários.

Veja também que esse projeto criado já tem nossa classe principal do SpringBoot para inicialização de nossa API. Busque por RatingRestApplication.java, ela deverá ser parecida com o código abaixo:

Vejá também que o projeto já tem uma classe de teste base para criarmos nossos testes unitários. Busque por RatingRestApplicationTests.java:

Para podermos usar o projeto junto com o demais vamos alterar a porta utilizada por padrão pelo projeto, alterando o application.properties que já veio em nosso projeto. Vamos adicionar a seguinte propriedade no arquivo:

API REST

Banco de Dados

Nós vamos utilizar o H2 Database, que permite que prototipemos projetos rapidamente, já que em um única biblioteca temos o Driver JDBC e o próprio Database Manager. Vamos insirir o bloco de dependência abaixo no pom.xml

Agora, vamos criar nossa classe de Entidade conforme abaixo:

Com base nessa classe, vamos agora criar uma nova classe em nosso projeto que será responsável pelas chamadas ao banco de dados.

Dessa forma toda a camada de persistência estará pronta para ser usada.

Vamos agora acertar os últimos detalhes do banco de dados. Adicione os seguintes itens no seu application.properties.

Rest Controller

Vamos criar uma classe para servir de Controller de nosso projeto REST conforme exemplo abaixo:

Podemos testar nossa aplicação rodando nossa aplicação usando:

E acesse o sistema em:

Documentação com Swagger

O Spring Fox é o framework construído no topo da API Swagger e integra-se ao framework do Spring. Spring Fox fornecerá as anotações que para integração com o framework do Swagger.

Em nosso projeto vamos usar o Swagger para documentar automaticamente nossa API.

Para isso, vamos adicionar as dependências necessárias no POM.xml.

Para utilizarmos o SpringFox em nosso projeto iremos criar uma classe de configuração com o nome SwaggerConfig, contendo a anotação @Configuration junto com o anotação @EnableSwagger2 com o seguinte conteúdo.

Podemos rodar nosso projeto agora e vamos o serviço disponibilizado pelo Swagger:

O retorno será um json enorme, a princípio incompreensível. O próprio Swagger nos fornece uma interface amigável para visualizarmos esse json.

Vamos alterar agora a nossa classe SwaggerConfig.java para exibir apenas os endpoints que precisamos:

Veja agora como ficou nossa interface de documentação:

Vamos agora personalizar as informações gerais da API. Alteremos a classe SwaggerConfig:

O resultado será algo parecido com esse:

Vamos agora alterar a classe RatingController

Veremos o resultado no método /ratings via GET.

Vamos agora alterar todos os demais métodos conforme fizemos com o primeiro:

Agora podemos atualizar e ver nossos endpoints:

Para aumentar os detalhes vamos acrescentar novas informações em nossa classe Rating.java:

Veja o resultado nessa mudança no método POST:

2 Comments

  1. Muito obrigado cara, Sou o Gilberto da Generation, e eu fico feliz por saber que a turma em que eu faço parte, está usando o seu modelo como exemplo

  2. Obrigada por compartilhar esse tutorial conosco.

Leave a Reply

Pin It on Pinterest