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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
<!-- Adicionar documentação automatizada de Swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> <!-- Compatibilidade com spring data rest --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-data-rest</artifactId> <version>2.6.1</version> </dependency> |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } } |
Para habilitarmos em nosso projeto a documentação dos endpoints do SpringDataRest, vamos adicionar o seguinte @Import em nossa classe SwaggerConfig.
|
1 2 |
@Import({springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration.class}) public class SwaggerConfig { |
Podemos rodar nosso projeto agora e vamos o serviço disponibilizado pelo Swagger:
|
1 2 |
http://localhost:8083/v2/api-docs |
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.
|
1 2 |
http://localhost:8083/swagger-ui.html |
Se expandirmos o o link do Book Entity, teremos acesso aos endpoints existentes de Livros.
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
.build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { ApiInfo apiInfo = new ApiInfoBuilder() .title ("API de Livros") .description ("Essa é a API de Livros criada para o treinamento.") .license("License of API") .licenseUrl("API license URL") .termsOfServiceUrl("Terms of service") .version("1.0.0") .contact(new Contact("Marcel Ferry","www.marcelferry.com.br", "marcelferry@marcelferry.com.br")) .build(); return apiInfo; } |
Agora veremos as alterações na tela do Swagger.
Pronto agora temos nossa api documentada.
