fastapi

FastAPI Skill

Load this file when working on a FastAPI project. Use alongside all skills/common/ files.

---

Stack

Layer	Library
Framework	FastAPI 0.111+
ASGI Server	Uvicorn with Gunicorn workers (prod)
ORM	SQLAlchemy 2.x async + Alembic
Validation	Pydantic v2
Auth	python-jose / PyJWT + passlib
HTTP Client	httpx (async)
Task Queue	Celery + Redis (or ARQ for lighter workloads)
Settings	pydantic-settings

---

Project Structure (FastAPI-specific additions)

app/
├── main.py                   ← App factory: create_app()
├── core/
│   ├── config.py
│   ├── security.py
│   ├── exceptions.py
│   └── logging.py
├── api/
│   ├── deps.py               ← Shared FastAPI dependencies
│   ├── v1/
│   │   ├── __init__.py
│   │   ├── router.py         ← Aggregates all v1 routers
│   │   ├── users.py
│   │   ├── auth.py
│   │   └── health.py
├── models/                   ← SQLAlchemy ORM models
├── schemas/                  ← Pydantic request/response models
├── repositories/
├── services/
└── workers/                  ← Background task definitions

---

App Factory Pattern

# app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.core.config import settings
from app.core.logging import configure_logging
from app.core.exceptions import AppBaseException, app_exception_handler
from app.api.v1.router import v1_router

def create_app() -> FastAPI:
    """Application factory."""
    configure_logging(log_level=settings.log_level, json_logs=not settings.debug)

    app = FastAPI(
        title=settings.app_name,
        version=settings.app_version,
        docs_url="/docs" if settings.debug else None,   # hide Swagger in prod
        redoc_url="/redoc" if settings.debug else None,
    )

    app.add_middleware(CORSMiddleware, allow_origins=settings.allowed_origins, ...)
    app.add_exception_handler(AppBaseException, app_exception_handler)
    app.include_router(v1_router, prefix="/api/v1")

    return app

app = create_app()