Uma API auto-documentável com FastAPI, Pydantic e Tortoise ORM.
- Linguagem: Python
- Framework: FastAPI
- ORM: Tortoise ORM
- Documentação: Swagger (automática via FastAPI)
- Banco de Dados: PostgreSQL
- Autenticação: JWT
- Gerenciamento de Dependências: uv
- Validação: Pydantic
- Migrations: Aerich
- Hash de Senhas: Passlib
| Diretório/Arquivo | Descrição |
|---|---|
| migrations/ | Migrações do banco de dados (Aerich) |
| src/ | Código-fonte principal da aplicação |
| └─ controllers/ | Controladores para lidar com requisições HTTP |
| └─ auth/ | Endpoints de autenticação (sign-up, sign-in, profile) |
| └─ models/ | Modelos do banco de dados (Tortoise ORM) |
| └─ schemas/ | Esquemas de validação de dados (Pydantic) |
| └─ utils/ | Funções utilitárias e helpers |
| └─ main.py | Configuração principal da aplicação FastAPI |
| └─ database.py | Configurações do banco de dados e Tortoise ORM |
| docker-compose.yml | Configuração do PostgreSQL via Docker |
| pyproject.toml | Dependências e configurações do projeto |
| Makefile | Comandos úteis para desenvolvimento |
| Método | Endpoint | Descrição | Autenticação |
|---|---|---|---|
| GET | /health |
Health check da API | ❌ |
| POST | /auth/sign-up |
Registrar um novo usuário | ❌ |
| POST | /auth/sign-in |
Fazer login e obter o token de autenticação | ❌ |
| GET | /auth/profile |
Obter o perfil do usuário autenticado | ✅ |
Clone o repositório na sua máquina:
git clone https://github.com/izaiasmorais/fastapi-cleanAcesse o projeto:
cd fastapi-cleanInstale o UV (se ainda não tiver):
curl -LsSf https://astral.sh/uv/install.sh | shCrie e ative o ambiente virtual:
uv venv
source .venv/bin/activateInstale as dependências:
uv syncConfigure o arquivo .env com suas credenciais (crie baseando-se nas variáveis usadas no código):
SECRET_KEY="seu-secret-key-super-seguro"
ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30
DATABASE_URL="postgresql://postgres:postgres123@localhost:5432/fastapi_auth"Rode o banco PostgreSQL no Docker:
docker compose up -dInicialize as migrações do Aerich (apenas na primeira vez):
uv run aerich init -t src.database.TORTOISE_ORMCrie a primeira migração:
uv run aerich init-dbPara migrações futuras, use:
uv run aerich migrate
uv run aerich upgradeInicie o servidor de desenvolvimento:
make devOu manualmente:
uv run python -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000A API estará disponível em: http://localhost:8000
A documentação Swagger estará em: http://localhost:8000 (configurado como página inicial)
# Servidor de desenvolvimento com reload automático
make dev
# Servidor de produção
make start# Inicializar migrações (apenas primeira vez)
uv run aerich init -t src.database.TORTOISE_ORM
# Criar primeira migração
uv run aerich init-db
# Criar nova migração após mudanças nos modelos
uv run aerich migrate
# Aplicar migrações
uv run aerich upgrade# Subir apenas o PostgreSQL
docker compose up -d
# Parar os serviços
docker compose down
# Ver logs do PostgreSQL
docker compose logs postgres