Cícero Ednilson

Blog sobre Desenvolvimento de Softwares

Home » Spring Boot e Swagger, documentando e testando a sua API REST.

Spring Boot e Swagger, documentando e testando a sua API REST.

0 Flares Twitter 0 Facebook 0 Filament.io 0 Flares ×

Nesse tutorial vamos aprender como documentar a nossa API REST feita com Spring Boot, para isso vou usar um tutorial que fiz aqui.

Introdução.

O Swagger é uma ferramenta que pode ser usada em todo o ciclo de desenvolvimento de uma API REST, desde o design até os testes, e essa ferramenta está disponível para várias linguagens como PHP, C#, Java entre outras, nesse tutorial vamos apenas ver como documentar e testar a nossa API com o Swagger.

Configurando o Swagger no nosso projeto.

Vamos abrir o nosso arquivo pom.xml e vamos adicionar as depêndencias abaixo.

1
2
3
4
5
6
7
8
9
10
11
12
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
    <scope>compile</scope>
</dependency>

Agora vamos criar uma classe com o nome de SwaggerConfig, depois vamos deixar nossa classe com o código abaixo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
package br.com.ciceroednilson;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@EnableSwagger2
@Configuration
public class SwaggerConfig {
 
	@Bean
	public Docket detalheApi() {
 
		Docket docket = new Docket(DocumentationType.SWAGGER_2);
 
		docket
		.select()
		.apis(RequestHandlerSelectors.basePackage("br.com.ciceroednilson"))
		.paths(PathSelectors.any())
		.build()
		.apiInfo(this.informacoesApi().build());
 
		return docket;
	}
 
	private ApiInfoBuilder informacoesApi() {
 
		ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
 
		apiInfoBuilder.title("Api-Pessoa");
		apiInfoBuilder.description("Api para realização de um CRUD.");
		apiInfoBuilder.version("1.0");
		apiInfoBuilder.termsOfServiceUrl("Termo de uso: Deve ser usada para estudos.");
		apiInfoBuilder.license("Licença - Open Source");
		apiInfoBuilder.licenseUrl("http://www.ciceroednilson.com.br");
		apiInfoBuilder.contact(this.contato());
 
		return apiInfoBuilder;
 
	}
	private Contact contato() {
 
		return new Contact(
				"Cícero Ednilson",
				"http://www.ciceroednilson.com.br", 
				"ciceroednilson@gmail.com");
	}
}

Nessa classe colocamos as configurações necessárias para executar o Swagger e algumas informações para a nossa API, veja na imagem abaixo onde adicionei a classe no meu projeto.

Agora vamos abrir a classe que representa as operações da nossa API, que no meu caso é a classe PessoaService, o método que vou alterar é o salvar, veja abaixo como ele está hoje sem o Swagger.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
	@Autowired
	private PessoaRepository pessoaRepository; 
 
	/**
	 * SALVAR UM NOVO REGISTRO
	 * @param pessoa
	 * @return
	 */
	@RequestMapping(value="/pessoa", method = RequestMethod.POST, consumes=MediaType.APPLICATION_JSON_UTF8_VALUE,produces=MediaType.APPLICATION_JSON_UTF8_VALUE)
	public @ResponseBody ResponseModel salvar(@RequestBody PessoaModel pessoa){
 
 
		try {
 
			this.pessoaRepository.save(pessoa);
 
			return new ResponseModel(1,"Registro salvo com sucesso!");
 
		}catch(Exception e) {
 
			return new ResponseModel(0,e.getMessage());			
		}
	}

Agora vamos deixar o nosso método como mostra o código abaixo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
	@Autowired
	private PessoaRepository pessoaRepository; 
 
 
 
	@ApiOperation(
			value="Cadastrar uma nova pessoa", 
			response=ResponseModel.class, 
			notes="Essa operação salva um novo registro com as informações de pessoa.")
	@ApiResponses(value= {
			@ApiResponse(
					code=200, 
					message="Retorna um ResponseModel com uma mensagem de sucesso",
					response=ResponseModel.class
					),
			@ApiResponse(
					code=500, 
					message="Caso tenhamos algum erro vamos retornar um ResponseModel com a Exception",
					response=ResponseModel.class
					)
 
	})
	@RequestMapping(value="/pessoa", method = RequestMethod.POST, consumes=MediaType.APPLICATION_JSON_UTF8_VALUE,produces=MediaType.APPLICATION_JSON_UTF8_VALUE)	
	public @ResponseBody ResponseEntity<ResponseModel> salvar(@RequestBody PessoaModel pessoa){
 
 
		try {
 
			this.pessoaRepository.save(pessoa);
 
			return new ResponseEntity<ResponseModel>(new ResponseModel(1,"Registro salvo com sucesso!"), HttpStatus.OK);
 
		}catch(Exception e) {
 
			return new ResponseEntity<ResponseModel>(new ResponseModel(0,e.getMessage()),HttpStatus.INTERNAL_SERVER_ERROR);			
		}
	}

Veja que no código acima temos as anotações @ApiOperation, @ApiResponses e @ApiResponse com as informações da nossa operação e os possíveis retornos, quando formos testar a nossa API vamos ver melhor onde essas anotações vão nos ajudar, abaixo vou deixar o código completo da classe, caso você tenha acompanhado o tutorial anterior tente documentar as outras operações.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
package br.com.ciceroednilson.service;
 
import java.util.List;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
 
import br.com.ciceroednilson.model.PessoaModel;
import br.com.ciceroednilson.model.ResponseModel;
import br.com.ciceroednilson.repository.PessoaRepository;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
 
@RestController
@CrossOrigin(origins  = "http://localhost:4200")
@RequestMapping("/service")
public class PessoaService {
 
	@Autowired
	private PessoaRepository pessoaRepository; 
 
 
 
	@ApiOperation(
			value="Cadastrar uma nova pessoa", 
			response=ResponseModel.class, 
			notes="Essa operação salva um novo registro com as informações de pessoa.")
	@ApiResponses(value= {
			@ApiResponse(
					code=200, 
					message="Retorna um ResponseModel com uma mensagem de sucesso",
					response=ResponseModel.class
					),
			@ApiResponse(
					code=500, 
					message="Caso tenhamos algum erro vamos retornar um ResponseModel com a Exception",
					response=ResponseModel.class
					)
 
	})
	@RequestMapping(value="/pessoa", method = RequestMethod.POST, consumes=MediaType.APPLICATION_JSON_UTF8_VALUE,produces=MediaType.APPLICATION_JSON_UTF8_VALUE)	
	public @ResponseBody ResponseEntity<ResponseModel> salvar(@RequestBody PessoaModel pessoa){
 
 
		try {
 
			this.pessoaRepository.save(pessoa);
 
			return new ResponseEntity<ResponseModel>(new ResponseModel(1,"Registro salvo com sucesso!"), HttpStatus.OK);
 
		}catch(Exception e) {
 
			return new ResponseEntity<ResponseModel>(new ResponseModel(0,e.getMessage()),HttpStatus.INTERNAL_SERVER_ERROR);			
		}
	}
 
 
	@RequestMapping(value="/pessoa", method = RequestMethod.PUT, consumes=MediaType.APPLICATION_JSON_UTF8_VALUE)
	public @ResponseBody ResponseModel atualizar(@RequestBody PessoaModel pessoa){
 
		try {
 
			this.pessoaRepository.save(pessoa);		
 
			return new ResponseModel(1,"Registro atualizado com sucesso!");
 
		}catch(Exception e) {
 
			return new ResponseModel(0,e.getMessage());
		}
	}
 
 
	@RequestMapping(value="/pessoa", method = RequestMethod.GET, produces=MediaType.APPLICATION_JSON_UTF8_VALUE)
	public @ResponseBody List<PessoaModel> consultar(){
 
		return this.pessoaRepository.findAll();
	}
 
 
	@RequestMapping(value="/pessoa/{codigo}", method = RequestMethod.GET, produces=MediaType.APPLICATION_JSON_UTF8_VALUE)
	public @ResponseBody PessoaModel buscar(@PathVariable("codigo") Integer codigo){
 
		return this.pessoaRepository.findOne(codigo);
	}
 
 
	@RequestMapping(value="/pessoa/{codigo}", method = RequestMethod.DELETE, produces=MediaType.APPLICATION_JSON_UTF8_VALUE)
	public @ResponseBody ResponseModel excluir(@PathVariable("codigo") Integer codigo){
 
		PessoaModel pessoaModel = pessoaRepository.findOne(codigo);
 
		try {
 
			pessoaRepository.delete(pessoaModel);
 
			return new ResponseModel(1, "Registro excluido com sucesso!");
 
		}catch(Exception e) {
			return new ResponseModel(0, e.getMessage());
		}
	}
 
}

Testando API REST com Swagger.

Agora vamos executar a nossa API e acessar a url http://localhost:8090/swagger-ui.html, aqui estou executando a minha API com o Tomcat Embedded que já vem no Spring Boot, depois de realizarmos a request no endereço da nossa API devemos ver a página abaixo.

Veja na imagem acima que podemos visualizar as informações que definimos na classe SwaggerConfig, agora vamos clicar em List Operations como mostra a imagem abaixo.

E então vamos ver as operações da nossa API como mostra a imagem abaixo.

Agora vamos clicar na opção Cadastrar uma nova pessoa, e então vamos ver os detalhes que descrevemos nas anotações do Swagger.

Mais abaixo podemos ver um exemplo do json que devemos enviar para salvar uma nova pessoa, então vamos clicar sobre o exemplo e depois vamos remover do json o campo “codigo”, pois na hora de inserir não precisamos dele.

Agora vamos clicar no botão Try it out! para testar a nossa operação.

E então devemos receber o resultado como mostra a imagem abaixo.

Bom nesse tutorial vimos como documentar e testar a nossa API com Swagger, se você seguiu o tutorial da criação dessa API tente documentar as outras operações.

Até o próximo tutorial.

Comentários

Name of author

Name: ciceroednilson@gmail.com

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

0 Flares Twitter 0 Facebook 0 Filament.io 0 Flares ×