fastapi_skill

Overview

This skill provides production-tested patterns for building Python APIs with FastAPI, Pydantic v2, and SQLAlchemy 2.0 async, including JWT authentication, validation rules, and async database integration. It includes a recommended domain-based project structure, auth flows, and fixes to seven documented FastAPI pitfalls. Use the provided patterns with the uv package manager for fast setup and reliable defaults.

How this skill works

The skill supplies ready-to-use scaffolding: app lifespan, CORS setup, async SQLAlchemy engine and session factory, Pydantic v2 schemas (with from_attributes), and router/service patterns. It implements JWT creation/verification, password hashing, dependency-based current-user resolution, and example CRUD endpoints. It also documents specific workarounds for common FastAPI errors (form metadata, 422 validation, CORS, blocking calls, background tasks, OpenAPI mismatches, and async mistakes).

When to use it

• Starting a new FastAPI project with async SQLAlchemy and Pydantic v2
• Implementing JWT-based auth and protected routes
• Structuring code by domain for maintainability and tests
• Troubleshooting 422 validation, CORS, or OpenAPI schema problems
• Avoiding blocking calls and other async-related production issues

Best practices

• Organize code by domain (routers, schemas, models, services, dependencies) not by file type
• Keep Pydantic schemas separate from SQLAlchemy models and use from_attributes=True for responses
• Use async for all I/O (async DB sessions, async HTTP, async file ops) and avoid blocking calls in routes
• Use dependency injection (Depends) for DB sessions and auth to keep routes thin
• Validate inputs with Field() constraints and separate Create/Update/Response schemas
• Store secrets and configuration in env variables via Pydantic Settings, never hardcode secrets

Example use cases

• Create a CRUD API with async SQLite/Postgres using SQLAlchemy 2.0 async and uv to run dev server
• Add registration, login, and protected endpoints using JWTs and OAuth2PasswordBearer
• Fix form handling or field metadata issues by using individual Form parameters or JSON bodies
• Build a maintainable resume-matching microservice with domain modules for parsing, scoring, and embeddings
• Enable predictable CORS for a Next.js frontend by specifying origin(s) instead of using wildcard