Swagger • IzaTec

Vamos configurar uma documentação de uma API com Swagger.

Mas antes vamos saber o que significa o Swagger.

Swagger é uma linguagem de descrição de interface, para descrever APIs RESTful expressas usando JSON. O Swagger é usado junto com um conjunto de ferramentas de software de código aberto para projetar, construir, documentar e usar serviços da Web RESTful.

Exemplos de exibição da página contendo todos os serviços de uma API REST

Conforme vimos anteriormente, podemos criar um novo projeto no https://start.spring.io/.

Caso prefira, você pode usar o projeto que criamos anteriormente Primeiro Projeto.

Configurando o Projeto

Abra o arquivo pom.xml e adicione as dependências do Swagger conforme código abaixo:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

A partir da versão 3 do Spring Boot, é necessário que a versão do Java seja no mínimo a 17.

O Maven possui um repositório central que nos ajuda a encontrar uma variedade de dependências para cada necessidade de nossos projetos: MVNRepository.

Criando um Controller

Crie uma classe contendo serviços de GET / POST / PUT e DELETE para representar operações de CRUD, em um Usuário.

Ou se preferir, adicione as configurações do swagger no nosso projeto de Controle de Usuários, que estamos implementando.

Primeiro criamos a classe Usuario.java:

public class Usuario {
    private String login;
    private String password;
    public Usuario() {}
    public Usuario(String login, String password) {
        this.login = login;
        this.password = password;
    }
    @Override
    public String toString() {
        return "User{" +
                "login='" + login + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
    
    ... getters e setters
}

Depois vamos criar a classe UsuarioRepository.java que represente um Repository:

@Repository
public class UsuarioRepository {
    public void save(Usuario usuario){
        System.out.println("SAVE - Recebendo o usuário na camada de repositório");
        System.out.println(usuario);
    }
    public void update(Usuario usuario){
        System.out.println("UPDATE - Recebendo o usuário na camada de repositório");
        System.out.println(usuario);
    }
    public void remove(Integer id){
        System.out.println(String.format("DELETE/id - Recebendo o id: %d para excluir um usuário", id));
        System.out.println(id);
    }
    public List<Usuario> listAll(){
        System.out.println("LIST - Listando os usários do sistema");
        List<Usuario> usuarios = new ArrayList<>();
        usuarios.add(new Usuario("gleyson","password"));
        usuarios.add(new Usuario("frank","masterpass"));
        return usuarios;
    }
    public Usuario finById(Integer id){
        System.out.println(String.format("FIND/id - Recebendo o id: %d para localizar um usuário", id));
        return new Usuario("gleyson","password");
    }

}

Hora de criar a classe UsuarioController.java:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
public class UsuarioController {
    @Autowired
    private UsuarioRepository repository;

    @PostMapping("/usuarios")
    public void post(@RequestBody Usuario usuario){
        repository.save(usuario);
    }
    @PutMapping("/usuarios")
    public void put(@RequestBody Usuario usuario){
        repository.update(usuario);
    }
    @GetMapping("/usuarios")
    public List<Usuario> getAll(){
        return repository.listAll();
    }
    @GetMapping("/usuario/{id}")
    public Usuario getOne(@PathVariable("id") Integer id){
        return repository.finById(id);
    }
    @DeleteMapping("/usuarios/{id}")
    public void delete(@PathVariable("id") Integer id){
        repository.remove(id);
    }
}

Testando a API

Após iniciar a aplicação, acesse os recursos através do link:

http://localhost:8080/swagger-ui/index.html

Prontinho, aqui estão os métodos da nossa API!

Ao final da nossa prática, nossa estrutura do projeto ficou assim:

Referências

Spring Web

Introdução

Vamos aprofundar na manipulação de arquivos.