Olá pessoal! hoje vamos criar uma documentação de Api utilizando Swagger com Spring Boot, vamos aprender a como configurar o projeto e ver na prática o funcionamento desta ferramenta para auxiliar em nossos projetos.
O que é Swagger?
Swagger é um conjunto de ferramentas de software de código aberto que auxilia desenvolvedores na criação, documentação e teste de APIs de forma eficiente e padronizada.
Originalmente desenvolvido pela SmartBear Software, o projeto Swagger foi posteriormente renomeado como OpenAPI Specification.
OpenAPI Specification (OAS)
A especificação OpenAPI é uma especificação de linguagem agnóstica que descreve a estrutura de uma API RESTful.
Ela permite que desenvolvedores, em diferentes linguagens de programação, compreendam os endpoints disponíveis, os parâmetros necessários, os formatos de dados aceitos e outras informações cruciais para interagir com a API.
Integração do Swagger com Spring Boot
A integração do Swagger com Spring Boot é simples, permitindo a geração automatizada da documentação da API. Isso pode ser feito utilizando a biblioteca springfox-swagger2 em conjunto com springfox-swagger-ui para integrar o Swagger à aplicação Spring Boot.
Configuração do Swagger
Para integrar o Swagger a uma aplicação Spring Boot, precisamos adicionar as dependências springfox-swagger2 e springfox-swagger-ui ao arquivo pom.xml (no caso de um projeto Maven) ou ao arquivo de configuração do gerenciador de dependências utilizado.
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
Com as dependências adicionadas em nosso projetos, precisamos criar uma classe SwaggerConfiguration, onde vamos iniciar as configurações do Swagger e algumas informações importantes para ajudar a descrever uma Api.
Preencha todos os dados conforme a sua Api e sua informações, seguindo as configurações abaixo:
Classe SwaggerConfiguration:
package br.com.virandoprogramador.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Collections;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket retornaSwagger() {
return new Docket(DocumentationType.SWAGGER_2).select()
.apis(RequestHandlerSelectors.basePackage("br.com.virandoprogramador"))
.paths(PathSelectors.any())
.build()
.apiInfo(informacoesApi());
}
private ApiInfo informacoesApi() {
return new ApiInfo("Api Virando Programador - Cadastro de Pessoas",
"Disponibilizando Recursos das Apis de Cadastro de Pessoas",
"V1", "Api - Livre",
new Contact("Guilherme Santos", "https://virandoprogramador.com.br/", "virandoprogramador@teste"),
null, null, Collections.emptyList());
}
}Observe que está classe está anotada com uma anotação do Spring Boot @Configuration, por que justamente precisamos dizer para o Framework que está classe precisa “setar” algumas configurações para utilizarmos no Swagger.
Com a nossa classe de configurações completa, precisamos criar uma Api Rest em nosso projeto Spring Boot.
Se você já tiver uma classe Controller com alguns métodos, você pode pular está parte, no meu caso vou criar uma classe de controlador para podermos utilizar e documentar nossa Api:
Como criar API no Swagger?
Bom para que nosso projeto funcione perfeitamente, vamos criar a seguinte classe abaixo, onde vai estar nossos 5 endpoints (CRUD) para modificar dados de uma pessoa.
Classe PessoaController:
package br.com.virandoprogramador.controller;
import java.util.List;
import javax.validation.Valid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import br.com.virandoprogramador.dto.ModelPessoasDTO;
import br.com.virandoprogramador.model.ModelPessoas;
import br.com.virandoprogramador.service.PessoaService;
import io.swagger.annotations.ApiOperation;
@RestController
@RequestMapping(value = "/api/v1/pessoas")
public class PessoaController {
@Autowired
private PessoaService pessoaService;
@ApiOperation(value = "Endpoint Salvar Pessoas")
@PostMapping(value = "/salvaPessoas")
public ModelPessoas salvaPessoas(@RequestBody @Valid ModelPessoas modelPessoas) {
for (int posicao = 0; posicao < modelPessoas.getContatos().size(); posicao++) {
modelPessoas.getContatos().get(posicao).setPessoas(modelPessoas);
}
return pessoaService.salvar2(modelPessoas);
}
@ApiOperation(value = "Endpoint Lista todas Pessoas")
@GetMapping(value = "/listarTodos")
public List<ModelPessoasDTO> findAll() {
return pessoaService.findAll();
}
@ApiOperation(value = "Endpoint Pesquisar Pessoa por ID")
@GetMapping("/pesquisar/{id}")
public ModelPessoasDTO findById(@PathVariable("id") Long id) {
return pessoaService.findById(id);
}
@ApiOperation(value = "Endpoint Atualizar Pessoa")
@PutMapping(value = "/atualizar")
public ModelPessoasDTO atualizaPessoas(@RequestBody ModelPessoasDTO modelPessoasDTO) {
return pessoaService.atualizar(modelPessoasDTO);
}
@ApiOperation(value = "Endpoint Deletar Pessoa")
@DeleteMapping("/delete/{id}")
public ResponseEntity<?> delete(@PathVariable("id") Long id) {
pessoaService.delete(id);
return ResponseEntity.ok().build();
}
}Como Acessar o Swagger?
para acessar o Swagger você primeiro precisa configurar todo o projeto como nós realizamos nos passos anteriores, e digitar no navegador a seguinte url: http://localhost:8080/swagger-ui.html.
Agora vamos acessar nossa parte visual do Swagger e ver nossos endpoints. Se não houve nenhum problema de configuração, devemos ver a seguinte tela abaixo:
Atualmente temos 5 endpoints que configuramos em nossa classe de Controller:
- salvaPessoas
- findAll
- findById
- atualizaPessoas
- delete
Exemplo de um teste para salvar uma Pessoa:
Basta inserir os dados de cadastro de pessoa em seu endpoint, ao executar ele irá validar as informações e salvar no Banco de Dados.
Bom, terminamos! estas são as configurações básicas de como começar a documentar uma Api Spring Boot com Swagger, conforme você vai criar novos endpoints o Swagger vai atualizando.
Swagger, finalizando sobre o assunto
Em resumo, o Swagger desempenha um papel bem importante na facilitação do desenvolvimento de APIs ao oferecer uma maneira padronizada e automatizada de criar documentação clara e interativa.
Sua utilidade vai além da documentação, fornecendo recursos para teste, padronização e colaboração entre equipes, melhorando a eficiência e a qualidade no desenvolvimento de software.
Aqui no meu projeto fica dando o erro:
Ao acessar http://localhost:8080/swagger-ui/index.html recebo o erro Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.
Olá, bom podem ser algumas coisas a causa do erro, nas classes de controller você está adicionando a anotação correta? @RestController? se sim, qual seria a versão do seu projeto Spring Boot?