Criando nosso primeiro serviço REST com SpringBoot – Parte 4

Introdução

Essa é a quarta parte deste tutorial, caso não esteja acompanhando, pode acessar as outras partes em:

Criando nosso primeiro serviço REST com SpringBoot – Parte 1

Criando nosso primeiro serviço REST com SpringBoot – Parte 2

Criando nosso primeiro serviço REST com SpringBoot – Parte 3

Swagger com SpringFox

O Swagger é um projeto composto por algumas ferramentas que auxiliam o desenvolvedor de APIs REST em algumas tarefas como:

  • Modelagem da API
  • Geração de documentação (legível) da API
  • Geração de códigos do Cliente e do Servidor, com suporte a várias linguagens de programação

Para isso, o Swagger especifica a OpenAPI, uma linguagem para descrição de contratos de APIs REST. A OpenAPI define um formato JSON com campos padronizados (através de um JSON Schema) para que você descreva recursos, modelo de dados, URIs, Content-Types, métodos HTTP aceitos e códigos de resposta.

Como nosso objetivo nesse tutorial é ação, vamos deixar as explicações para outro artigo.

O Spring Fox é o framework construido 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.

Observe que para o projeto construído na parte 2 deste tutorial, apenas as duas primeiras dependências são necessárias. A terceira dependência será necessária para que o Swagger “exergue” os endpoints automáticos gerados pelos Spring Data Rest.

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.

Para habilitarmos em nosso projeto a documentação dos endpoints do SpringDataRest, vamos adicionar o seguinte @Import em nossa classe SwaggerConfig.

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.

Tela do Swagger

Se expandirmos o o link do Book Entity, teremos acesso aos endpoints existentes de Livros.

Book Entity - Detalhes do Livro

Podemos acessar agora o método get e veremos o detalhamento do método:

Se clicarmos no botão “Try it out”, você poderá executar o método e ver o seu resultado.

Agora vamos colocar algumas informações para auxiliar na documentação da nossa api. Faça as seguintes alterações no seu arquivo SwaggerConfig.java.

Agora veremos as alterações na tela do Swagger.

Pronto agora temos nossa api documentada.

Leave a Reply

Pin It on Pinterest