RESTful Desenvolvimento da API para projeto do bootcamp Java AI Powered da DIO.
Construída com Java 21 e Spring Boot 3.2.3.
Este é um projeto de API criado a partir de desafio de projeto do bootcamp Java AI Powered da DIO.
O primeiro desafio foi fazer uma abstração de um JSON que atendesse uma tela de amostra de uma aplicação feita no Figma, sem seguida
gerar diagrama de classe com a sintaxe mermaid utilizando prompt em uma IA Generativa (por exemplo, ChatGPT) com o JSON criado.
Com a resposta, aprimorei o diagrama para criar uma API que pode atender uma situação problema real para cadastro e controle
de estudantes, cursos, turmas, matrículas e notas e atenda à tela da amostra.
As sigla ESS foi formada pelo nome Escola Shining Star, nome criado para representar o produto deste projeto.
A API foi construída com Java e SpringBoot com objetivo de gerar cadastro e controle para estudantes, cursos, turmas,
matrículas e notas que uma instituição que possui serviços compatíveis possa utilizar.
Este projeto disponibiliza Endpoints que viabilizam o cadastro e controle. Os endpoints estão documentados com
swagger e também estão configurados em coleção do postman para serem utilizados com o aplicativo para realizar as chamadas
e testes.
Aqui foram abordadas as etapas:
- Amostra com Figma: visual de uma tela de aplicativo, no caso, um aplicativo que mostra notas de um aluno.
- Diagrama de classes: Utilizando IA para elaorar diagrama de classes através de um JSON extraído conforme amostra.
- Criação da API ESS
- Criação de conta e de banco de dados Postgres utilizando a plataforma Railway
- Publicação da API no Railway utilizando a integração com o GitHub
- As variáveis de ambientes comfiguradas para PRD foram configuradas no recurso do Railway
- Adicionalmente, como foi utilizado o Java 21 nesse projeto, foi necessário configurar a variável de ambiente "NIXPACKS_JDK_VERSION" com o valor "21".
- Java 21: Versão LTS mais recente do Java para tirar vantagem das últimas inovações que essa linguagem robusta e amplamente utilizada oferece;
- Spring Boot 3: Versão do Spring Boot, que maximiza a produtividade do desenvolvedor por meio de sua poderosa premissa de autoconfiguração;
- Spring Data JPA: Ferramenta pode simplificar a camada de acesso aos dados, facilitando a integração com bancos de dados SQL;
O projeto iniciou com a montagem de uma amostra da aplicação utilizando o Figma para ser base para a abstração de informações para dar seguimento ao projeto.
🔗 Amostra no Figma
Diagrama de classes com sintaxe Mermaid, criado a partir da abstração de atributos em JSON com base na amostra do Figma e prompt com Microsoft Copilot.
Ver diagrama de classes criado com Microsoft Copilot
classDiagram
class Student {
- name: string
- guardian: string
- photo: string
- class: Class
- subjects: Subject[]
- messages: Message[]
- shortcuts: Shortcut[]
- news: News[]
}
class Class {
- name: string
- frequency: string
- period: string
- status: string
}
class Subject {
- name: string
- grade: Grade
}
class Grade {
- type: string
- value: number
}
class Message {
- description: string
- dateTime: string
- read: boolean
}
class Shortcut {
- icon: string
- name: string
}
class News {
- title: string
- description: string
}
Student o-- Class
Student o-- Subject
Subject *-- Grade
Student o-- Message
Student o-- Shortcut
Student o-- News
Prompt utilizado no Microsoft Copilot
Gere um diagrama de classes (usando a sintaxe Mermaid) tendo em vista o seguinte JSON que repretanta um aluno de uma escola. Inclua as relações entre as classes. Traduza os nomes das classes e atributos para o inglês. Mantenha uma estrutura simples e fiel ao modelo que vou passar: { "nome": "Maria", "responsavel": "João", "foto": "urlFoto", "turma": { "nome": "1º Ano - A", "periodicidade": "Anual", "periodo": "2024", "status": "Em curso" }, "materias": [ { "nome": "Português", "nota": { "tipo": "Final", "valor": 10 } }, { "nome": "Matemática", "nota": { "tipo": "Final", "valor": 10 } }, { "nome": "Ciências", "nota": { "tipo": "Em curso", "valor": 0 } } ], "mensagens":[ { "descricao": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "dataHora": "2024-03-02T13:02:34.000Z", "lida": false }, { "descricao": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "dataHora": "2024-03-01T08:02:34.000Z", "lida": true } ], "atalhos": [ { "icone": "urlIcone", "nome": "Conferir Pagamentos" }, { "icone": "urlIcone2", "nome": "Falar com a Secretaria" }, { "icone": "urlIcone3", "nome": "Autorizar Saída" } ], "novidades": [ { "titulo": "Confira o calendário escolar", "descricao": "Veja os feriados, data das provas e das férias." }, { "titulo": "Ensino Integral", "descricao": "Veja aqui as atividades programadas para o período da tarde." } ] }Com base no diagrama criado pela IA e a documentação do Mermaid, o diagrama foi editado para deixar as classes no padrão Java e criar as relações para o JPA:
classDiagram
class BasicEntity {
<<Abstract>>
- UUID id
}
class BasicItem {
<<Abstract>>
- String icon
- String title
- String description
}
class Student {
- String givenName
- String familyName
- String guardian
- String photo
}
class Course {
- String name
- Frequency frequency
- Set~Message~ messages
- Set~News~ news
- Set~Shortcut~ shortcuts
}
class Clazz {
- String name
- Course course
- LocalDate initDate
- LocalDate recoveryDate
- LocalDate endDate
}
class RegistrationId {
- Student student
- Clazz clazz
}
class Registration {
- RegistrationId id
- Set~Subject~ subjects
- LocalDate registrationDate
+ RegistrationStatus status()
}
class Frequency {
<<Enumeration>>
YEARLY
SEMI_ANNUAL
QUARTERLY
BIMONTHLY
MONTHLY
}
class RegistrationStatus {
<<Enumeration>>
ONGOING
APPROVED
RECOVERY
DISAPPROVED
}
class Message {
- LocalDateTime dateTime
}
class GradeId {
- Registration registration
- Subject subject
}
class Grade {
- GradeId id
- GradeType type
- BigDecimal value
}
class GradeType {
<<Enumeration>>
FINAL
PARTIAL
ONGOING
}
class Shortcut {
- String link
}
class News
class Subject
BasicEntity <|-- BasicItem
BasicEntity <|-- Course
BasicEntity <|-- Clazz
BasicEntity <|-- Student
BasicItem <|-- Message
BasicItem <|-- News
BasicItem <|-- Shortcut
BasicItem <|-- Subject
Course ..> Frequency
Course *-- Message
Course *-- News
Course *-- Shortcut
Clazz --> Course
RegistrationId --* Student
RegistrationId --* Clazz
RegistrationId <|-- Registration
Registration --> Subject
Registration ..> RegistrationStatus
Grade ..> GradeType
GradeId <|-- Grade
GradeId --* Registration
GradeId --* Subject
O legal desta etapa foi ver que, apesar de no modelo do Figma ter o Estudante como base, este não era necessariamente o domínio central, existe uma dependência forte com Curso, Turma e Matrícula para ter a relação do estudante com as matérias e notas.
Logotipo do produto ESS Escola Shining Star
Banner do Spring personalizado
Console do H2 (banco de dados) mostrando as tabelas criadas e os dados de uma tabela de relação de muitos para muitos que relaciona o Estudante, a Turma e a Matéria matriculada
Abaixo print do recurso de Postgres criado no Railway
Retorno de erro com DTO personalizado com tratamento para timestamp, status, mensagem e path utilizando a classe me.didi.api.ess.dtos.ApiErrorDTO
Swagger do projeto
Requisição com Swagger na API hospedada no Railway
Relatório de coverage gerado pelo Jacoco
Retorno de erro na validação de boby em requests, no exemplo é um POST de nova nota (grade) com o body vazio, portanto retorna os campos e respectivas mensagens:
Quando utiliza chamada de POST que cria novo recurso, seja um estudante, curso, turma ou mesmo o registro da matrícula, o retorno tem
o header "Location" que possui link direto para chamar o recurso específico (GET para findById).
Abaixo exemplo de retorno de cadastro de um Estudante:
Abaixo exemplo de um retorno mais complexo como o Registro de Matrícula:
Os testes foram feitos utilizando [JUnit 5], Mockito e MockMVC com Hamcrest.
-
Para executar os testes pode executar sua IDE ou
-
Utilizando o terminal (PowerShell, Bash ou similiar), basta executar na pasta do projeto o comando abaixo:
./mvnw clean test
Após o teste finalizado com sucesso, é possível verificar relatório de coverage em: target/site/jacoco/index.html
Antes de mais nada, é preciso Possuir no mínimo JDK 21 LTS instalado na máquina em que irá executar. A execução do projeto pode ser feita utilizando atalhos de sua IDE ou com os comandos abaixo:
./mvnw clean package spring-boot:repackage
java -jar target/ess-0.0.1-SNAPSHOT.jarOBS: caso ocorra erro e estiver utilizando o terminal CMD, no primeiro comando basta remover o "./" antes do mvnw
Para acessar a documentação do Swagger OpenAPI v3.1, acesso o link com o projeto em execução: http://localhost:8080/swagger-ui/index.html
Neste projeto tem arquivo de coleção do Postman com os Endpoints configurados: ESS.postman_collection.json
Para popular dados automaticamente foram criadas classes que executam ao iniciar a aplicação, assim a aplicação já inicia com dados básicos para gets.
As classes estão no pacote me.didi.api.ess.utils.populate.
Melhorias e desafios para aprimorar o projeto:
- Criar recurso para alterar estudantes, curso e turma
- Criar endpoint para adicionar ou remover matérias na matrícula
- Configurar paginação para os endpoints que retornam lista (findAll)
- Criar recurso para poder apagar estudantes, curso, turma, matéria, matrícula, nota, mensagem, notícia e atalho:
- Para este caso ter atenção com a consistência de dados
- De preferência utilizar soft delete para permitir reverter a deleção
- Aprimorar documentação OpenApi/Swagger com exemplos e descrições para os endpoints e schemas
- Observabilidade: implementar logs e métricas
- Implementar cache
- Incluir e configurar método de autenticação e autorização (por exemplo, Spring Security)
- Incluir e configurar versionamento de banco utilizando, por exemplo, flyway
- Utilizar uma solução de banco de dados diferente do H2 (MySQL, Postgres, etc)
- Criar testes de Integração
- Criar front-end/app para consumir a API
- Criar testes e2e
📋 Qualquer dúvida, sugestão ou crítica é só entrar em contato ou abrir uma Issue (https://github.com/didifive).
💚 Feito com muita dedicação e aprendizado. #EnjoyThis