📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Especialização em Backend com Python e FastAPI. Recomendado revisar antes de começar.

🐍 API de Controle de Gastos com Python & FastAPI

📁 Código deste projeto: api-fastapi/ (os caminhos citados abaixo são relativos à subpasta).

v1.0 — FastAPI, Pydantic v2, SQLAlchemy 2.0 e Swagger OpenAPI Automático

Trilha de Especialização Pedagógica — Projeto 1 de 4

• ➡️ v1 (este): API RESTful Assíncrona · FastAPI · Pydantic v2 · SQLite
• v2: Autenticação OAuth2 com JWT & Hashing Passlib
• v3: Integração com Celery, Redis & Tarefas Assíncronas
• v4: Microsserviços com Docker, Pytest & Cobertura 100%

🎓 Nível Profissional Simulado: Desenvolvedor Python Júnior. FastAPI revolucionou o desenvolvimento backend em Python com sua velocidade extrema, validação automática baseada em Type Hints com Pydantic v2 e documentação Swagger gerada sem nenhum esforço manual.

🎯 Objetivo & Escopo do Projeto

Construir uma API RESTful Assíncrona de Controle Financeiro em Python 3.12 + FastAPI, utilizando Pydantic v2 para validação estrita de esquemas e SQLAlchemy 2.0 para persistência de dados com documentação interativa em /docs.

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Equipe Financeira)

“Precisamos de uma API moderna em Python para registrar lançamentos de despesas. A API deve validar que nenhum valor seja negativo, que as datas sejam válidas e deve disponibilizar uma interface Swagger interativa para os desenvolvedores testarem os endpoints direto pelo navegador.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

📋 Fase 2 — Backlog & User Stories

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Branch da funcionalidade
git checkout -b feature/US01-fastapi-pydantic-crud

# Executar a API com Uvicorn em modo reload
uvicorn main:app --reload --port 8000

🛠️ Fase 4 — Implementação Guiada (main.py)

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field

app = FastAPI(title="Controle de Gastos API", version="1.0.0")

class GastoSchema(BaseModel):
    id: int | None = None
    descricao: str
    valor: float = Field(gt=0, description="O valor deve ser estritamente positivo")

banco_memoria = []

@app.post("/gastos", status_code=status.HTTP_201_CREATED)
def criar_gasto(gasto: GastoSchema):
    gasto.id = len(banco_memoria) + 1
    banco_memoria.append(gasto)
    return gasto

@app.get("/gastos")
def listar_gastos():
    return banco_memoria

🚀 Roteiro de Execução

1. Criar Ambiente e Instalar Dependências

cd catalogo_projetos/python_web_gastos_01_fastapi/api-fastapi
python -m venv .venv
source .venv/bin/activate  # No Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Iniciar a API com Uvicorn

uvicorn app.main:app --reload --port 8000

3. Acessar a Documentação Interativa

Abra no navegador http://localhost:8000/docs para visualizar a documentação interativa gerada pelo Swagger UI.

🧭 Decisões de Arquitetura (ADRs)

• ADR 001: Adoção do FastAPI e Pydantic v2 para geração automática de contratos OpenAPI e validação estrita.

🧪 Testes de Validação & Swagger

• Acesse http://localhost:8000/docs para validar o Swagger interativo gerado em tempo de execução.

✅ Checkpoint Final

1. Endpoints RESTful respondendo no FastAPI.
2. Pydantic bloqueando valores <= 0 com código 422.