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.

		<!-- 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>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

</dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-data-rest</artifactId>

</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.

@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();
    }

}

@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.

@Import({springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration.class})
public class 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:

http://localhost:8083/v2/api-docs

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.

http://localhost:8083/swagger-ui.html

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.

          .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;
    }

.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.