Escola API

API REST para cadastro de usuários e gerenciamento de alunos. O projeto demonstra uma aplicação Spring Boot em camadas, persistência com JPA/PostgreSQL, validação de entrada e autenticação stateless com JWT.

• Java 21 e Maven Wrapper
• Spring Boot 3.5.14
• Spring Web, Spring Data JPA, Spring Security e Bean Validation
• PostgreSQL
• Auth0 Java JWT e BCrypt
• Springdoc OpenAPI/Swagger UI
• JUnit 5, Mockito, MockMvc e Testcontainers

• Cadastro de usuário com senha armazenada como hash BCrypt
• Login com emissão de JWT
• CRUD de alunos em rotas protegidas
• Validação declarativa dos dados de alunos e usuários
• Resposta estruturada para erros de validação
• Contrato OpenAPI e interface Swagger UI

O código está organizado em controller, service, repository, model, dto, config e exception.

HTTP -> Controller -> Service -> Repository -> PostgreSQL
           |             |
          DTO       regra de nota

Os controllers definem o contrato HTTP; AlunoService concentra a validação de nota e as operações do domínio; os repositórios Spring Data JPA cuidam da persistência. DTOs separam a entrada e a saída usadas no cadastro de alunos.

1. Cadastre um usuário em POST /usuarios.
2. Envie login e senha para POST /login.
3. Use o token retornado nas rotas de alunos:

Authorization: Bearer <token>

O SecurityFilter valida o token, recupera o usuário pelo login e preenche o contexto do Spring Security. A aplicação não cria sessão no servidor. Os tokens são emitidos pelo TokenService com issuer API Escola e expiração de duas horas.

POST /usuarios, POST /login e os recursos do Swagger são públicos. As demais rotas exigem autenticação.

Cadastro e login:

POST /usuarios
Content-Type: application/json

{
  "login": "andre",
  "senha": "uma-senha-segura"
}

POST /login
Content-Type: application/json

{
  "login": "andre",
  "senha": "uma-senha-segura"
}

Cadastro de aluno:

POST /alunos
Authorization: Bearer <token>
Content-Type: application/json

{
  "nome": "Maria Silva",
  "nota": 8.5,
  "turma": "A",
  "idade": 16
}

• id: identificador gerado pelo banco
• login: obrigatório e único
• senha: obrigatória e persistida como hash BCrypt

• id: identificador gerado pelo banco
• nome: obrigatório, não vazio e limitado a 100 caracteres na coluna
• nota: obrigatória, entre 0 e 10
• turma: opcional
• idade: opcional e não negativa

Entradas inválidas produzem HTTP 400 com timestamp, status, mensagem e erros por campo por meio de GlobalExceptionHandler.

Com a aplicação em execução:

• Swagger UI: http://localhost:8080/swagger-ui.html
• Documento OpenAPI: http://localhost:8080/v3/api-docs

Essas rotas são públicas para permitir a exploração e autenticação pela interface.

As propriedades aceitam variáveis de ambiente, com valores locais padrão definidos em application.properties:

Forneça valores próprios fora do código em ambientes compartilhados ou de produção. O Hibernate está configurado com ddl-auto=update; use uma estratégia de migrations antes de operar o projeto em produção.

Pré-requisitos: JDK 21 e PostgreSQL. Docker também é necessário para executar o teste de integração com Testcontainers.

git clone https://github.com/AndreLopes30/escola-java-api.git
cd escola-java-api

# Linux/macOS
./mvnw spring-boot:run

# Windows
.\mvnw.cmd spring-boot:run

A API usa http://localhost:8080 por padrão.

# Linux/macOS
./mvnw test

# Windows
.\mvnw.cmd test

A suíte contém três níveis comprováveis no código:

• testes unitários de AlunoService com Mockito;
• testes de controller com @WebMvcTest e MockMvc;
• testes de persistência com @DataJpaTest e PostgreSQL 16 em Testcontainers.

O workflow de CI executa a mesma suíte no Ubuntu com Java 21. O Maven Wrapper mantém a versão do Maven reproduzível sem exigir instalação global.

src/
├── main/
│   ├── java/com/andre/escola_api/
│   │   ├── config/
│   │   ├── controller/
│   │   ├── dto/
│   │   ├── exception/
│   │   ├── model/
│   │   ├── repository/
│   │   └── service/
│   └── resources/application.properties
└── test/java/com/andre/escola_api/

• JWT e SessionCreationPolicy.STATELESS evitam estado de sessão no servidor.
• DTOs evitam acoplar o contrato de criação de aluno diretamente à entidade persistida.
• Testcontainers exercita o mapeamento JPA contra PostgreSQL real e descartável.
• spring.jpa.open-in-view=false mantém o acesso ao banco fora da fase de serialização HTTP.

• Adotar migrations versionadas, como Flyway ou Liquibase, em vez de ddl-auto=update.
• Ampliar os testes de autenticação, autorização e tratamento de erros.
• Padronizar respostas de erro também para recursos inexistentes e conflitos de unicidade.
• Adicionar paginação e filtros à listagem de alunos.

Desenvolvido por André Ferreira — GitHub · LinkedIn