samfert · staging-devin-ai-integration · Jan 9, 2026
diff --git a/README.md b/README.md
@@ -0,0 +1,339 @@
+# FastAPI Simple App Example
+
+Uma aplicacao FastAPI de exemplo que demonstra uma estrutura basica de API REST com operacoes CRUD para gerenciamento de posts.
+
+## Descricao do Projeto
+
+Este projeto e uma aplicacao de exemplo que implementa uma API REST completa utilizando FastAPI, um framework moderno e de alta performance para construcao de APIs em Python. A aplicacao demonstra boas praticas de desenvolvimento, incluindo separacao de responsabilidades, uso de ORM, validacao de dados e documentacao automatica.
+
+### Tecnologias Utilizadas
+
+- **FastAPI**: Framework web moderno e de alta performance para construcao de APIs
+- **SQLAlchemy**: ORM (Object-Relational Mapping) para interacao com o banco de dados
+- **Pydantic**: Validacao de dados e serializacao usando type hints do Python
+- **PostgreSQL**: Banco de dados relacional
+- **Alembic**: Ferramenta de migracao de banco de dados
+- **Docker**: Containerizacao da aplicacao
+- **Poetry**: Gerenciamento de dependencias Python
+- **Uvicorn**: Servidor ASGI de alta performance
+
+## Estrutura do Projeto
+
+```
+fastapi-simple-app-example/
+├── app/                          # Pacote principal da aplicacao
+│   ├── __init__.py              # Inicializacao do pacote e versao
+│   ├── config.py                # Configuracoes da aplicacao (variaveis de ambiente)
+│   ├── main.py                  # Aplicacao FastAPI e endpoints da API
+│   ├── models.py                # Modelos SQLAlchemy (tabelas do banco de dados)
+│   ├── schemas.py               # Schemas Pydantic (validacao de entrada/saida)
+│   ├── actions.py               # Operacoes CRUD (Create, Read, Update, Delete)
+│   └── db/                      # Configuracao do banco de dados
+│       ├── __init__.py          # Exporta Base e importa modelos
+│       ├── base.py              # Classe Base declarativa do SQLAlchemy
+│       └── session.py           # Engine e SessionLocal do SQLAlchemy
+├── migrations/                   # Migracoes do Alembic
+│   ├── env.py                   # Configuracao do ambiente Alembic
+│   └── versions/                # Scripts de migracao
+│       └── ee48ba03fe9f_create_posts_table.py
+├── tests/                        # Testes da aplicacao
+│   ├── __init__.py
+│   └── test_app.py              # Testes unitarios
+├── .env.example                  # Exemplo de variaveis de ambiente
+├── alembic.ini                   # Configuracao do Alembic
+├── docker-compose.yml            # Configuracao do Docker Compose
+├── docker-compose.override.yml   # Override para desenvolvimento
+├── Dockerfile                    # Imagem Docker da aplicacao
+├── pyproject.toml               # Configuracao do Poetry e dependencias
+├── poetry.lock                  # Lock file das dependencias
+└── prestart.sh                  # Script executado antes de iniciar a aplicacao
+```
+
+## Requisitos
+
+- Python 3.8 ou superior
+- PostgreSQL 12 ou superior
+- Poetry (para gerenciamento de dependencias)
+- Docker e Docker Compose (opcional, para execucao containerizada)
+
+## Instalacao e Configuracao
+
+### Opcao 1: Instalacao Local
+
+1. Clone o repositorio:
+```bash
+git clone https://github.com/samfert-codeium/fastapi-simple-app-example.git
+cd fastapi-simple-app-example
+```
+
+2. Instale as dependencias usando Poetry:
+```bash
+poetry install
+```
+
+3. Configure as variaveis de ambiente. Copie o arquivo de exemplo e edite conforme necessario:
+```bash
+cp .env.example .env
+```
+
+4. Edite o arquivo `.env` com suas configuracoes:
+```env
+# PostgreSQL
+POSTGRES_SERVER=localhost
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=sua_senha
+POSTGRES_DB=app
+```
+
+5. Crie o banco de dados PostgreSQL:
+```bash
+createdb app
+```
+
+6. Execute as migracoes do banco de dados:
+```bash
+poetry run alembic upgrade head
+```
+
+### Opcao 2: Usando Docker
+
+1. Clone o repositorio:
+```bash
+git clone https://github.com/samfert-codeium/fastapi-simple-app-example.git
+cd fastapi-simple-app-example
+```
+
+2. Configure as variaveis de ambiente:
+```bash
+cp .env.example .env
+```
+
+3. Inicie os containers:
+```bash
+docker-compose up -d
+```
+
+Isso ira iniciar:
+- Servidor da aplicacao FastAPI na porta 8000
+- Banco de dados PostgreSQL
+- PgAdmin na porta 8080 (para administracao do banco)
+
+## Como Executar o Projeto
+
+### Execucao Local
+
+Ative o ambiente virtual do Poetry e inicie o servidor:
+```bash
+poetry run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Execucao com Docker
+
+```bash
+docker-compose up
+```
+
+A aplicacao estara disponivel em: http://localhost:8000
+
+### Documentacao Interativa
+
+Apos iniciar a aplicacao, acesse:
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+## Endpoints da API
+
+A API fornece os seguintes endpoints para gerenciamento de posts:
+
+| Metodo | Endpoint | Descricao |
+|--------|----------|-----------|
+| GET | `/` | Health check / boas-vindas |
+| GET | `/posts` | Lista todos os posts (com paginacao) |
+| POST | `/posts` | Cria um novo post |
+| GET | `/posts/{id}` | Recupera um post especifico |
+| PUT | `/posts/{id}` | Atualiza um post existente |
+| DELETE | `/posts/{id}` | Remove um post |
+
+## Exemplos de Uso da API
+
+### Health Check
+
+```bash
+curl http://localhost:8000/
+```
+
+Resposta:
+```json
+{"message": "Hello world!"}
+```
+
+### Criar um Post
+
+```bash
+curl -X POST http://localhost:8000/posts \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Meu Primeiro Post", "body": "Conteudo do post aqui..."}'
+```
+
+Resposta (201 Created):
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "title": "Meu Primeiro Post",
+  "body": "Conteudo do post aqui..."
+}
+```
+
+### Listar Posts
+
+```bash
+curl http://localhost:8000/posts
+```
+
+Com paginacao:
+```bash
+curl "http://localhost:8000/posts?skip=0&limit=10"
+```
+
+Resposta:
+```json
+[
+  {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "title": "Meu Primeiro Post",
+    "body": "Conteudo do post aqui..."
+  }
+]
+```
+
+### Obter um Post Especifico
+
+```bash
+curl http://localhost:8000/posts/123e4567-e89b-12d3-a456-426614174000
+```
+
+Resposta:
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "title": "Meu Primeiro Post",
+  "body": "Conteudo do post aqui..."
+}
+```
+
+### Atualizar um Post
+
+```bash
+curl -X PUT http://localhost:8000/posts/123e4567-e89b-12d3-a456-426614174000 \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Titulo Atualizado"}'
+```
+
+Resposta:
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "title": "Titulo Atualizado",
+  "body": "Conteudo do post aqui..."
+}
+```
+
+### Deletar um Post
+
+```bash
+curl -X DELETE http://localhost:8000/posts/123e4567-e89b-12d3-a456-426614174000
+```
+
+Resposta:
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "title": "Titulo Atualizado",
+  "body": "Conteudo do post aqui..."
+}
+```
+
+## Migracoes de Banco de Dados
+
+O projeto utiliza Alembic para gerenciamento de migracoes.
+
+### Aplicar Migracoes
+
+```bash
+poetry run alembic upgrade head
+```
+
+### Criar Nova Migracao
+
+```bash
+poetry run alembic revision --autogenerate -m "descricao da migracao"
+```
+
+### Reverter Ultima Migracao
+
+```bash
+poetry run alembic downgrade -1
+```
+
+### Ver Historico de Migracoes
+
+```bash
+poetry run alembic history
+```
+
+## Testes
+
+Execute os testes usando pytest:
+
+```bash
+poetry run pytest tests/
+```
+
+Com cobertura de codigo:
+
+```bash
+poetry run pytest tests/ --cov=app
+```
+
+## Dependencias
+
+### Producao
+
+- fastapi ^0.54.1 - Framework web
+- sqlalchemy ^1.3.16 - ORM
+- uvicorn ^0.11.5 - Servidor ASGI
+- email_validator ^1.1.0 - Validacao de email
+- psycopg2-binary ^2.8.5 - Driver PostgreSQL
+- python-dotenv ^0.13.0 - Carregamento de .env
+- alembic ^1.4.2 - Migracoes de banco de dados
+- inflect ^4.1.0 - Pluralizacao de palavras
+
+### Desenvolvimento
+
+- pytest ^5.2 - Framework de testes
+- flake8 ^3.8.1 - Linter
+- autopep8 ^1.5.2 - Formatador de codigo
+- mypy ^0.770 - Verificacao de tipos
+- isort ^4.3.21 - Ordenacao de imports
+- black ^19.10b0 - Formatador de codigo
+- sqlalchemy-stubs ^0.3 - Type stubs para SQLAlchemy
+
+## Variaveis de Ambiente
+
+| Variavel | Descricao | Exemplo |
+|----------|-----------|---------|
+| POSTGRES_SERVER | Endereco do servidor PostgreSQL | localhost |
+| POSTGRES_USER | Usuario do PostgreSQL | postgres |
+| POSTGRES_PASSWORD | Senha do PostgreSQL | password |
+| POSTGRES_DB | Nome do banco de dados | app |
+| PGADMIN_DEFAULT_EMAIL | Email do admin do PgAdmin | admin@local.host |
+| PGADMIN_DEFAULT_PASSWORD | Senha do PgAdmin | password |
+| PGADMIN_LISTEN_PORT | Porta do PgAdmin | 8080 |
+
+## Licenca
+
+Este projeto e disponibilizado como exemplo educacional.
+
+## Autor
+
+Alexander van Zyl <vanzyl.alex@gmail.com>
diff --git a/app/__init__.py b/app/__init__.py
@@ -1 +1,23 @@
-__version__ = "0.1.0"
+"""
+FastAPI Simple App Example.
+
+Este pacote contém uma aplicação FastAPI de exemplo que demonstra
+uma estrutura básica de API REST com operações CRUD para posts.
+
+A aplicação utiliza:
+    - FastAPI para o framework web
+    - SQLAlchemy para ORM e interação com banco de dados
+    - Pydantic para validação de dados
+    - PostgreSQL como banco de dados
+    - Alembic para migrações de banco de dados
+
+Modules:
+    config: Configurações da aplicação usando variáveis de ambiente
+    models: Modelos SQLAlchemy para o banco de dados
+    schemas: Schemas Pydantic para validação de entrada/saída
+    actions: Operações CRUD genéricas e específicas
+    main: Endpoints da API FastAPI
+    db: Configuração de conexão com o banco de dados
+"""
+
+__version__: str = "0.1.0"