Finance API Spring Boot

REST API for personal finance management, built with Java 17, Spring Boot, Spring Data JPA, H2 Database and Swagger/OpenAPI.

This project is part of my backend learning path. I built it to practice REST API development, layered architecture, validation, database persistence, error handling and API documentation.

---

Overview

Finance API is a simple backend application for managing personal financial records.

The API allows users to create, list, update, delete and mark financial records as paid. It also includes a summary endpoint that calculates income, expenses and balance.

The project was designed to be simple enough to understand, but organized enough to show backend fundamentals used in real applications.

---

Features

• Create a financial record
• List all financial records
• Get a record by ID
• Update an existing record
• Delete a record
• Mark or unmark a record as paid
• Calculate financial summary
• Validate request data
• Return JSON responses
• Handle common API errors
• Provide Swagger/OpenAPI documentation
• Use H2 database for local development

---

Technologies Used

Area	Technologies
Language	Java 17
Framework	Spring Boot
API	Spring Web
Database	H2 Database
Persistence	Spring Data JPA
Validation	Bean Validation
Documentation	Swagger/OpenAPI
Build Tool	Maven

---

Project Structure

finance-api-springboot/
├── src/main/java/com/luancabral/financeapi/
│   ├── controller/
│   ├── dto/
│   ├── exception/
│   ├── model/
│   ├── repository/
│   ├── service/
│   └── FinanceApiApplication.java
├── src/main/resources/
│   ├── application.properties
│   └── data.sql
├── api-examples.http
├── pom.xml
├── README.md
└── .gitignore

---

Data Model

id          Long
descricao   String
categoria   String
tipo        RECEITA or DESPESA
valor       BigDecimal
data        LocalDate
pago        Boolean

---

API Endpoints

Base URL:

http://localhost:8080

Method	Endpoint	Description
GET	/api/lancamentos	List all records
GET	/api/lancamentos/{id}	Get a record by ID
POST	/api/lancamentos	Create a new record
PUT	/api/lancamentos/{id}	Update a record
PATCH	/api/lancamentos/{id}/pago	Toggle paid status
DELETE	/api/lancamentos/{id}	Delete a record
GET	/api/lancamentos/resumo	Get financial summary

---

Example Request

POST /api/lancamentos
Content-Type: application/json

{
  "descricao": "Salario",
  "categoria": "Trabalho",
  "tipo": "RECEITA",
  "valor": 1200.00,
  "data": "2026-07-10",
  "pago": true
}

Example Response

{
  "id": 1,
  "descricao": "Salario",
  "categoria": "Trabalho",
  "tipo": "RECEITA",
  "valor": 1200.00,
  "data": "2026-07-10",
  "pago": true
}

Summary Example

{
  "totalReceitas": 1200.00,
  "totalDespesas": 121.40,
  "saldo": 1078.60
}

---

How to Run Locally

git clone https://github.com/luancabral1/finance-api-springboot.git
cd finance-api-springboot
mvn spring-boot:run

The API should run on:

http://localhost:8080

Swagger documentation:

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

H2 console:

http://localhost:8080/h2-console
JDBC URL: jdbc:h2:mem:finance_db
User: sa
Password:

---

What I Practiced

• REST API development with Spring Boot
• Layered architecture with controller, service and repository
• Data persistence with Spring Data JPA
• Request validation
• Error handling with a global exception handler
• DTO usage for request and response data
• Financial summary calculation
• Swagger/OpenAPI documentation
• H2 database for local testing

---

Future Improvements

• Add authentication
• Add filtering by category, type and date
• Add pagination
• Add unit and integration tests
• Add Docker support
• Add MySQL or MariaDB profile
• Deploy the API

---

Status

Project in development.

---

Author

Developed by Luan Cabral.

• GitHub: @luancabral1
• LinkedIn: Luan Cabral

---

License

This project is licensed under the MIT License.

---

Versão em Português

API REST para gestão de finanças pessoais, desenvolvida com Java 17, Spring Boot, Spring Data JPA, H2 Database e Swagger/OpenAPI.

Este projeto faz parte do meu percurso de aprendizagem em backend. Desenvolvi-o para praticar criação de APIs REST, arquitetura em camadas, validação, persistência em base de dados, tratamento de erros e documentação de API.

---

Visão Geral

A Finance API é uma aplicação backend simples para gerir lançamentos financeiros pessoais.

A API permite criar, listar, atualizar, apagar e marcar lançamentos como pagos. Também inclui um endpoint de resumo que calcula receitas, despesas e saldo.

---

Funcionalidades

• Criar lançamento financeiro
• Listar todos os lançamentos
• Buscar lançamento por ID
• Atualizar lançamento existente
• Apagar lançamento
• Marcar ou desmarcar lançamento como pago
• Calcular resumo financeiro
• Validar dados recebidos
• Retornar respostas em JSON
• Tratar erros comuns da API
• Fornecer documentação Swagger/OpenAPI
• Usar H2 Database para desenvolvimento local

---

Como Executar Localmente

git clone https://github.com/luancabral1/finance-api-springboot.git
cd finance-api-springboot
mvn spring-boot:run

A API deverá ficar disponível em:

http://localhost:8080

Documentação Swagger:

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

---

O Que Pratiquei

• Desenvolvimento de API REST com Spring Boot
• Arquitetura em camadas com controller, service e repository
• Persistência com Spring Data JPA
• Validação de requisições
• Tratamento global de erros
• Uso de DTOs para entrada e saída de dados
• Cálculo de resumo financeiro
• Documentação Swagger/OpenAPI