🩸 📚 Documentação Detalhada - DoadorController

Sistema DoeSangue - Documentação Técnica
Gerado em 28/08/2025, 08:51:33 | Versão 1.0

📚 Documentação Detalhada - DoadorController

Data: 27 de Agosto de 2025
Autor: Winston (Dev Agent)
Finalidade: Estudo de caso para desenvolvimento de controllers REST

🎯 Objetivo deste Controller

O DoadorController foi criado como um exemplo completo demonstrando as melhores práticas para desenvolvimento de APIs REST no Spring Boot com documentação Swagger profissional. Este controller serve como template de referência para implementação de outros controllers no sistema.

📋 Estrutura do Controller

🗂️ Arquivos Criados:

src/main/java/com/faculdade/doesangue_api/
├── controllers/
│   └── DoadorController.java           # Controller principal
└── dtos/
    ├── DoadorCreateDTO.java           # DTO para criação
    ├── DoadorDTO.java                 # DTO para resposta
    └── DoadorFiltroDTO.java           # DTO para filtros

📊 Estatísticas do Código:

🚀 Funcionalidades Implementadas

1. 📋 Listagem Paginada com Filtros

GET /api/doadores?page=0&size=20&nome=João&tipoSanguineo=O+

Características:

Filtros Disponíveis:

2. 🔍 Busca por ID

GET /api/doadores/{id}

Características:

3. ➕ Cadastro de Novo Doador

POST /api/doadores

Características:

Validações Implementadas:

4. 🔄 Atualização de Dados

PUT /api/doadores/{id}

Características:

5. 🩺 Verificação de Aptidão

GET /api/doadores/{id}/aptidao

Características:

6. 📊 Estatísticas Detalhadas

GET /api/doadores/{id}/estatisticas

Características:

🏗️ Arquitetura dos DTOs

🔨 DoadorCreateDTO - Para Criação

Características:

Principais Validações:

@NotBlank(message = "Nome completo é obrigatório")
@Size(min = 2, max = 100, message = "Nome deve ter entre 2 e 100 caracteres")
private String fullName;

@Pattern(regexp = "\\d{11}", message = "CPF deve conter exatamente 11 dígitos numéricos")
private String cpf;

@Email(message = "Email deve ter formato válido")
private String email;

@AssertTrue(message = "Consentimento LGPD deve ser verdadeiro para prosseguir")
private Boolean consentimentoLgpd;

📤 DoadorDTO - Para Resposta

Características:

Campos Especiais:

@Schema(description = "CPF mascarado para privacidade", example = "123.***.***-01")
private String cpfMasked;

@Schema(description = "Idade calculada", accessMode = Schema.AccessMode.READ_ONLY)
private Integer idade;

@Schema(description = "Indica se pode doar no momento", accessMode = Schema.AccessMode.READ_ONLY)
private Boolean podeDoar;

🔍 DoadorFiltroDTO - Para Filtros

Características:

🔍 public record vs public class para DTOs

📝 public record - Moderna e Concisa (Java 14+)

Características:

Exemplo prático:

@Schema(description = "Dados para criação de doador")
public record DoadorCreateDTO(
    @Schema(description = "Nome completo", example = "João Silva")
    @NotBlank(message = "Nome completo é obrigatório")
    @Size(min = 2, max = 100, message = "Nome deve ter entre 2 e 100 caracteres")
    String fullName,
    
    @Schema(description = "CPF sem formatação", example = "12345678901")
    @Pattern(regexp = "\\d{11}", message = "CPF deve conter exatamente 11 dígitos numéricos")
    String cpf,
    
    @Schema(description = "Email para contato", example = "joao.silva@email.com")
    @Email(message = "Email deve ter formato válido")
    String email,
    
    @Schema(description = "Consentimento LGPD", example = "true")
    @AssertTrue(message = "Consentimento LGPD deve ser verdadeiro para prosseguir")
    Boolean consentimentoLgpd
) {}

✅ Vantagens:

🏗️ public class - Tradicional e Flexível

Características:

Exemplo prático:

@Schema(description = "Dados para criação de doador")
@Getter @Setter
@NoArgsConstructor @AllArgsConstructor
public class DoadorCreateDTO {
    
    @Schema(description = "Nome completo", example = "João Silva")
    @NotBlank(message = "Nome completo é obrigatório")
    @Size(min = 2, max = 100, message = "Nome deve ter entre 2 e 100 caracteres")
    private String fullName;
    
    @Schema(description = "CPF sem formatação", example = "12345678901")
    @Pattern(regexp = "\\d{11}", message = "CPF deve conter exatamente 11 dígitos numéricos")
    private String cpf;
    
    @Schema(description = "Email para contato", example = "joao.silva@email.com")
    @Email(message = "Email deve ter formato válido")
    private String email;
    
    @Schema(description = "Consentimento LGPD", example = "true")
    @AssertTrue(message = "Consentimento LGPD deve ser verdadeiro para prosseguir")
    private Boolean consentimentoLgpd;
    
    // Lombok gera getters, setters, construtores
}

✅ Vantagens:

🎯 Quando Usar Cada Um

Cenário Record Class
DTOs simples de transferência ✅ Preferível ⚠️ Adequado
Dados imutáveis ✅ Ideal ❌ Requer esforço extra
APIs REST modernas ✅ Recomendado ⚠️ Tradicional
Validações complexas ⚠️ Limitado ✅ Melhor
Herança necessária ❌ Não suporta ✅ Necessário
Java < 14 ❌ Não disponível ✅ Única opção
Frameworks antigos ⚠️ Pode ter problemas ✅ Compatível

💡 Recomendação para o Projeto DoeSangue

Para DTOs de Entrada/Saída:

// <span class="badge success">✅</span> RECOMENDADO - Record para dados simples
public record DoadorCreateDTO(
    @NotBlank String fullName,
    @Pattern(regexp = "\\d{11}") String cpf,
    @Email String email
) {}

// <span class="badge success">✅</span> ALTERNATIVO - Class quando precisar de flexibilidade
@Getter @Setter
public class DoadorUpdateDTO {
    private String fullName;
    private String email;
    
    // Métodos customizados de validação
    @AssertTrue
    public boolean isValidUpdate() {
        return fullName != null || email != null;
    }
}

📚 Conclusão:

📖 Documentação Swagger Avançada

🎨 Recursos Utilizados:

1. Anotações de Operação

@Operation(
    summary = "📋 Listar doadores com filtros avançados",
    description = """
        Descrição detalhada em markdown...
        
        **Funcionalidades:**
        - Item 1
        - Item 2
        
        **Casos de Uso:**
        - Caso 1
        - Caso 2
        """,
    tags = {"Doadores"}
)

2. Exemplos JSON Completos

@ExampleObject(
    name = "Exemplo completo de cadastro",
    value = """
        {
            "fullName": "Maria Oliveira Silva",
            "cpf": "98765432101",
            "email": "maria.oliveira@email.com",
            // ... JSON completo
        }
        """
)

3. Respostas Detalhadas

@ApiResponse(
    responseCode = "400", 
    description = "<span class="badge danger">❌</span> Dados inválidos fornecidos",
    content = @Content(
        schema = @Schema(implementation = Map.class),
        examples = @ExampleObject(
            value = """
                {
                    "error": "Bad Request",
                    "message": "Dados inválidos",
                    "details": {
                        "fullName": "Nome completo é obrigatório",
                        "cpf": "CPF deve conter exatamente 11 dígitos numéricos"
                    }
                }
                """
        )
    )
)

4. Parâmetros Documentados

@Parameter(
    description = "Número da página (iniciando em 0)", 
    example = "0",
    schema = @Schema(minimum = "0", defaultValue = "0")
)
@RequestParam(defaultValue = "0") int page

🎯 Benefícios da Documentação:

  1. Auto-explicativa - Desenvolvedores entendem sem explicação
  2. Testável - Todos os endpoints testáveis via Swagger UI
  3. Exemplos reais - JSON examples que funcionam
  4. Tratamento de erros - Todos os códigos HTTP documentados
  5. Validações claras - Regras explícitas para cada campo

🧪 Como Testar o Controller

1. Iniciar a Aplicação

cd doesangue_backend
./mvnw spring-boot:run

2. Acessar Swagger UI

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

3. Testar Endpoints

Listar Doadores:

GET /api/doadores?page=0&size=5&nome=João

Buscar por ID:

GET /api/doadores/1

Cadastrar Doador:

POST /api/doadores
{
    "fullName": "Novo Doador Teste",
    "cpf": "99999999999",
    "email": "teste@email.com",
    "birthDate": "1990-01-01",
    "gender": "M",
    "telefonePrincipal": "11999999999",
    "logradouro": "Rua Teste",
    "numero": "123",
    "cidade": "São Paulo",
    "estado": "SP",
    "cep": "01234567",
    "tipoSanguineoId": 1,
    "hemocentroId": 1,
    "cadastradoPorId": 1,
    "consentimentoLgpd": true
}

Verificar Aptidão:

GET /api/doadores/1/aptidao

4. Testar Validações

CPF Duplicado:

POST /api/doadores
{
    "cpf": "12345678901",  // CPF que já existe
    // outros campos...
}

Resultado esperado: 409 Conflict

Dados Inválidos:

POST /api/doadores
{
    "fullName": "",           // Nome vazio
    "cpf": "123",            // CPF inválido
    "email": "email-inválido", // Email inválido
    "consentimentoLgpd": false // LGPD não aceito
}

Resultado esperado: 400 Bad Request com detalhes

🎓 Conceitos Demonstrados

1. Spring Boot / Spring Web

2. Bean Validation

3. Swagger/OpenAPI 3

4. DTOs (Data Transfer Objects)

5. Paginação

6. Tratamento de Erros

🎯 Próximos Passos

Para Este Controller:

  1. Implementar Service layer - DoadorService com regras de negócio
  2. Implementar Repository - DoadorRepository com queries customizadas
  3. Integrar com entidades JPA - Mapear para Doador entity
  4. Adicionar testes - Unit e integration tests
  5. Implementar segurança - JWT authentication

Para Outros Controllers:

  1. UserController - Gestão de usuários
  2. HemocentroController - Gestão de hemocentros
  3. AuthController - Autenticação JWT
  4. TriagemController - Triagem clínica
  5. AgendamentoController - Agendamentos

Melhorias Arquiteturais:

  1. Exception Handler global - Tratamento centralizado de erros
  2. Audit logs - Auditoria automática de operações
  3. Cache - Cache para consultas frequentes
  4. Metrics - Métricas de performance
  5. Rate limiting - Controle de taxa de requisições

📚 Recursos de Aprendizado

Conceitos Aplicados:

Boas Práticas Demonstradas:

🎯 Conclusão: Este controller serve como um template completo para desenvolvimento de APIs REST profissionais no Spring Boot, demonstrando desde validações básicas até documentação avançada e tratamento de erros. É um exemplo prático de como implementar APIs de qualidade industrial.

📈 Valor para Aprendizado: Estudar este código fornece uma base sólida para desenvolvimento de APIs REST modernas, com foco em qualidade, documentação e manutenibilidade.

📋 Documentação gerada automaticamente | 🎯 Projeto DoeSangue

💻 Desenvolvido com ❤️ pela equipe de desenvolvimento