1 - Introdução 2 - Conceitos 3 - Importando projeto 4 - Dependências 5 - Customizando cabeçalho 6 - Rotas 7 - Modelos 8 - Considerações finais 9 - Considerações finais

6 - Rotas

Olá pessoal, essa é a sexta etapa do nosso tutorial de documentando projetos em Spring Boot, o foco agora é trabalhar com as rotas. Procure o seu arquivo de controle, no método de cadastro adicione a seguinte estrutura de annotations:

Essa é a estrutura utilizada no vídeo que está no YouTube, abaixo irei explicar em datalhes o que faz cada annotation, mas lembre-se que o método de cadastro possui uma validação, se ocorrer tudo bem o retorno será um 201 (criado), caso alguma informação esteja incorreta o retorno será um 400 (bad request).

@Operation - Essa annotation é uma espécie de título, irá aparecer ao lado do nome da rota;
@ApiResponses - Informamos os tipos de retorno, nesse exemplo temos dois retornos, sendo eles: 200 e 400. Também podemos implementar uma descrição e o uso da annotation @Content, que especifica o retorno da API, no caso um JSON e o modelo que irá retornar.

Execute o projeto e acesse a url: localhost:8080/swagger-ui.html, e veja atentamente como ficou a rota de cadastro (POST).

Abaixo irei deixar as annotations das demais rotas à disposição, caso queira fazer por conta, fique à vontade:

@RestController
@RequestMapping("/api")
public class Controle {

// ***** Disponibilizar um objeto do tipo Mensagem
    @Autowired
    private Mensagem mensagem;
    
    // ***** Lista de pessoas (simular um banco de dados)
    private List< Pessoa> lista = new ArrayList< Pessoa>();

// Código para efetuar o cadastro de pessoas
    int codigo = 0;

// ***** Rotas
    @PostMapping("/cadastrar")
    @Operation(summary = "Rota responsável pelo cadastro de pessoas")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "201", 
            description = "Pessoa cadastrada com sucesso",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Pessoa.class)
                )
            }
        ),

@ApiResponse(
            responseCode = "400", 
            description = "Informação inválida",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Mensagem.class)
                )
            }
        )
    })
    public ResponseEntity< ?> cadastrar(@RequestBody Pessoa p){

// Validação do nome (precisa ter pelo menos três caracteres)
        if(p.getNome().length() < 3){
            mensagem.setTexto("O nome deve ter pelo menos três caracteres.");
            return new ResponseEntity<Mensagem>(mensagem, HttpStatus.BAD_REQUEST);
        
        // Validação da idade (precisa ser uma idade entre 0 e 120)
        }else if(p.getIdade() < 0 || p.getIdade() > 120){
            mensagem.setTexto("Informe uma idade entre 0 e 120");
            return new ResponseEntity<Mensagem>(mensagem, HttpStatus.BAD_REQUEST);
        
        // Efetuar cadastro e retornar um objeto do tipo Pessoa
        }else{
            
            // Incrementar o código
            this.codigo += 1;

// Especificar o código no objeto do tipo Pessoa
            p.setCodigo(codigo);

// Adicionar o objeto do tipo Pessoa na lista
            this.lista.add(p);

// Retorno da API
            return new ResponseEntity< Pessoa>(p, HttpStatus.CREATED);
        }

}

@GetMapping("/listar")
    @Operation(summary = "Rota responsável pelo listagem de pessoas")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200", 
            description = "Listagem de pessoas",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Pessoa.class)
                )
            }
        )
    })
    public List< Pessoa> listarPessoas(){

// Retornar a lista de pessoas cadastradas
        return this.lista;

}

@GetMapping("/obterPessoa/{codigo}")
    @Operation(summary = "Rota responsável por obter uma pessoa através do código")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200", 
            description = "Pessoa encontrada",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Pessoa.class)
                )
            }
        ),

@ApiResponse(
            responseCode = "404", 
            description = "Pessoa não encontrada",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Mensagem.class)
                )
            }
        )
    })
    public ResponseEntity< ?> obterPessoa(@PathVariable long codigo){

// Criar um objeto Pessoa
        Pessoa p = new Pessoa();

// Realizar pesquisa na lista
        for (Pessoa pessoa : lista) {
            if(pessoa.getCodigo() == codigo){
                p = pessoa;
            }
        }

// Verifica o tipo de retorno
        if(p.getCodigo() == 0){

// Especifica um texto para o objeto mensagem
            mensagem.setTexto("Pessoa não encontrada");

// Retorno
            return new ResponseEntity< Mensagem>(mensagem, HttpStatus.NOT_FOUND);
        }else{

// Retorno
            return new ResponseEntity< Pessoa>(p, HttpStatus.OK);
        }

}

@PutMapping("/alterar")
    @Operation(summary = "Rota responsável pela alteração de dados das pessoas")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200", 
            description = "Pessoa alterada com sucesso",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Pessoa.class)
                )
            }
        ),

@ApiResponse(
            responseCode = "400", 
            description = "Falha ao localizar o alterar os dados da pessoa",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Mensagem.class)
                )
            }
        )
    })
    public ResponseEntity< ?> alterar(@RequestBody Pessoa p){

// Verificar a posição da pessoa informada na lista
        int posicaoAlteracao = -1;

for (int indice = 0; indice < this.lista.size(); indice++) {
            if(this.lista.get(indice).getCodigo() == p.getCodigo()){
                posicaoAlteracao = indice;
            }
        }

// Validar se o código informado existe
        if(posicaoAlteracao == -1){

mensagem.setTexto("O código informado não existe, tente novamente");
            return new ResponseEntity< Mensagem>(mensagem, HttpStatus.BAD_REQUEST);

// Validação do nome (precisa ter pelo menos três caracteres)
        }else if(p.getNome().length() < 3){
            mensagem.setTexto("O nome deve ter pelo menos três caracteres");
            return new ResponseEntity< Mensagem>(mensagem, HttpStatus.BAD_REQUEST);
        
        // Validação da idade (precisa ser uma idade entre 0 e 120)
        }else if(p.getIdade() < 0 || p.getIdade() > 120){
            mensagem.setTexto("Informe uma idade entre 0 e 120");
            return new ResponseEntity< Mensagem>(mensagem, HttpStatus.BAD_REQUEST);
        
        // Efetuar cadastro e retornar um objeto do tipo Pessoa
        }else{
            
            // Altera o objeto do tipo Pessoa na lista
            this.lista.set(posicaoAlteracao, p);

// Retorno da API
            return new ResponseEntity< Pessoa>(p, HttpStatus.OK);
        }

}

@DeleteMapping("/remover/{codigo}")
    @Operation(summary = "Rota responsável pela remoção de pessoas")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200", 
            description = "Pessoa removida com sucesso",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Mensagem.class)
                )
            }
        ),

@ApiResponse(
            responseCode = "400", 
            description = "Falha ao encontrar a pessoa ou remover",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = Mensagem.class)
                )
            }
        )
    })
    public ResponseEntity< Mensagem> remover(@PathVariable int codigo){

// Verificar a posição da pessoa informada na lista
        int posicaoRemocao = -1;

for (int indice = 0; indice < this.lista.size(); indice++) {
            if(this.lista.get(indice).getCodigo() == codigo){
                posicaoRemocao = indice;
            }
        }

// Verificação
        if(posicaoRemocao == -1){

// Mensagem
            mensagem.setTexto("O código informado não existe, tente novamente");

// Retorno
            return new ResponseEntity< Mensagem>(mensagem, HttpStatus.BAD_REQUEST);

}else{

// Remover pessoa da lista
            this.lista.remove(posicaoRemocao);

// Mensagem
            mensagem.setTexto("Pessoa removida com sucesso");

// Retorno
            return new ResponseEntity< Mensagem>(mensagem, HttpStatus.OK);
        }

}
}

Caso queira acompanhar essa etapa do tutorial através do vídeo, assista abaixo: