🚘 FIPE Explorer

FIPE Explorer é um projeto Java Spring Boot desenvolvido para consumir e explorar a API pública da Tabela FIPE (v2), permitindo consultar informações sobre marcas, modelos, anos e valores de veículos.
Foi criado com o propósito de estudo e prática de arquitetura em camadas, integração HTTP reativa e testes automatizados, mantendo qualidade e modularidade de código.

---

🧱 Estrutura do Projeto

fipeexplorer/
├── src/
│   ├── main/
│   │   ├── java/com/github/tiagogayer/fipeexplorer/
│   │   │   ├── config/           → Configuração do WebClient e Beans principais
│   │   │   ├── controller/       → Controladores REST
│   │   │   ├── dto/              → DTOs utilizados para mapear respostas da API FIPE
│   │   │   ├── exception/        → Exceções específicas de integração com a FIPE
│   │   │   ├── mapper/           → Conversores entre DTOs e modelos de domínio
│   │   │   ├── model/            → Modelos de domínio (Brand, Model, Vehicle, etc.)
│   │   │   ├── service/          → Serviços de integração e lógica de negócio
│   │   │   ├── util/             → Utilitários auxiliares (MockLoader, TextUtils, MenuMain)
│   │   │   └── FipeexplorerApplication.java
│   │   └── resources/
│   │       ├── application.yml / application-*.yml
│   │       └── mocks/            → Dados mockados para o perfil offline
│   └── test/
│       ├── java/com/github/tiagogayer/fipeexplorer/
│       │   ├── config/
│       │   ├── controller/
│       │   ├── integration/
│       │   ├── mapper/
│       │   ├── service/
│       │   ├── util/
│       │   └── BaseTest.java
│       └── resources/application.yml
│
├── .github/                      → Políticas e templates da comunidade
│   ├── ISSUE_TEMPLATE/
│   ├── SECURITY.md
│   └── pull_request_template.md
│
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── pom.xml
└── README.md

---

⚙️ Tecnologias Utilizadas

Categoria	Ferramenta
Linguagem	Java 21
Framework principal	Spring Boot 3.5.x
Cliente HTTP	Spring WebClient
Testes	JUnit 5, MockMvc, MockWebServer
Serialização	Jackson ObjectMapper
Build	Maven 3.9.x

---

🌐 Integração com a API FIPE

Endpoints consumidos:

• /api/v2/{vehicleType}/brands
• /api/v2/{vehicleType}/brands/{brandId}/models
• /api/v2/{vehicleType}/brands/{brandId}/models/{modelId}/years
• /api/v2/{vehicleType}/brands/{brandId}/models/{modelId}/years/{yearCode}

O método buildVehicle realiza essas chamadas para montar o objeto Vehicle completo, combinando marca, modelo, ano e preço.

---

🧩 Principais Componentes

Pacote / Classe	Responsabilidade
config/WebClientConfig	Configuração do cliente HTTP com token e URL base.
controller/FipeController	Endpoints REST principais para consulta FIPE.
service/FipeApiService	Cliente que executa requisições diretas à API FIPE.
service/impl/FipeMockService	Fornece dados mockados para o perfil offline.
model/	Estruturas de domínio (Brand, Model, Vehicle, etc.).
dto/	Objetos que mapeiam diretamente as respostas JSON da API.
mapper/	Conversão entre DTOs e modelos internos.
exception/	Exceções específicas para erros HTTP e indisponibilidade da FIPE.
util/MockLoader	Leitura de fixtures JSON locais para testes e mock.

---

🧪 Testes Automatizados

Suíte de testes abrangente cobrindo integração, mapeamento e simulações HTTP.

Classe	Descrição
BaseTest	Base de testes Spring Boot com utilitários e MockMvc.
WebClientConfigTest	Valida configuração e headers do WebClient.
JacksonConfigTest	Testa o comportamento do ObjectMapper e a serialização de campos nulos e vazios.
FipeIntegrationFlowTest	Teste ponta a ponta (E2E) com mock completo.
FipeMockServiceTest	Testes de cache e fallback no mock.
FipeServiceImplTest	Integração real com MockWebServer.
MapperTests	Validação das conversões entre DTOs e modelos.
TextUtilsTest	Testes de utilitários gerais.

Executar:

mvn clean test

---

⚙️ Perfis de Execução

Perfis Spring configurados para diferentes ambientes:

Profile	Descrição
dev	Ambiente de desenvolvimento, integração real com a FIPE.
prod	Ambiente de produção, com cache e logs otimizados.
mock	Ambiente offline com dados locais mockados.

Executar com perfil:

mvn spring-boot:run -Dspring-boot.run.profiles=mock

---

🧩 Tratamento de valores nulos (padrão de resposta da API)

A API FIPE Explorer adota um padrão de serialização consistente para todos os campos das respostas JSON, garantindo previsibilidade e compatibilidade com diferentes clientes.

🔹 Campos opcionais nunca retornam null.
🔹 Todos os campos permanecem presentes no JSON, mesmo quando não há valor disponível.
🔹 Strings nulas são convertidas em "" (string vazia).
🔹 Listas nulas são convertidas em [] (lista vazia).
🔹 Mapas nulos são convertidos em {} (objeto vazio).

Esse comportamento tem como objetivo:

• Evitar erros de desserialização em clientes front-end ou integrações externas.
• Garantir que o contrato da API seja fixo (campos sempre presentes).
• Manter a clareza semântica entre “campo existente, mas sem valor” e “campo inexistente”.

Exemplo:

{
  "code": 1,
  "acronym": "",
  "priceHistory": []
}

---

📈 Possíveis Melhorias

1. Melhorar política de retry:
   Avaliar incluir FipeApiUnavailableException (respostas 5xx) na lista de erros elegíveis para retry, permitindo reexecução automática de 503 transitórios.

2. Otimizar chamadas em buildVehicle:
   Atualmente o método realiza quatro requisições completas à FIPE. Caso novos endpoints sejam expostos, é possível reduzir latência e carga consolidando chamadas.

3. Aprimorar comportamento do perfil mock:
   Hoje o parâmetro de referência é ignorado. Se houver datasets dependentes da referência, será necessário versionar o cache para simular o comportamento real.

---

🌍 API Utilizada

Este projeto consome dados da API pública FIPE v2, mantida por Deivid Fortuna, que disponibiliza gratuitamente informações sobre marcas, modelos, anos e valores de veículos no Brasil.

Agradecimento especial ao autor por disponibilizar essa API aberta, que torna possível o desenvolvimento e estudo deste projeto. 🙏

---

👥 Contribuindo

Leia o CONTRIBUTING.md para diretrizes e boas práticas.

---

🛡️ Segurança e Conduta

• Código de conduta: CODE_OF_CONDUCT.md
• Política de segurança: GitHub Security Policy

---

👤 Autor

Tiago Arruda Gayer
LinkedIn • GitHub

Projeto de estudo em Java + Spring Boot, com foco em integração de APIs, testes automatizados e arquitetura limpa.