fastapi_skill

Overview

This skill provides practical, opinionated guidance for building and maintaining FastAPI applications. It focuses on project structure, request/response validation with Pydantic, routing, dependency injection, authentication, middleware, error handling, and async best practices. Use it whenever you read, edit, or create Python files that involve FastAPI, Starlette, or Pydantic models for web APIs.

How this skill works

The skill inspects FastAPI-related code patterns and suggests improvements across structure, typing, and runtime behavior. It checks for proper use of Pydantic models, APIRouters, dependency injection, async/await for I/O, and common middleware and error-handler patterns. It also guides implementing OAuth2/JWT authentication, background tasks, WebSocket endpoints, and clear response models with appropriate status codes.

When to use it

• Creating a new FastAPI app or project layout
• Adding or reviewing API endpoints or APIRouters
• Designing Pydantic request/response models and validation
• Implementing authentication (OAuth2/JWT) or protected routes
• Adding middleware, background tasks, WebSockets, or error handlers
• Refactoring sync I/O to async and improving dependency injection

Best practices

• Organize code into app/, routers/, models/, services/, and db/ for separation of concerns
• Use Pydantic models for all input/output and set model_config for ORM compatibility
• Keep route handlers thin; move business logic to service modules
• Prefer async/await for database and HTTP I/O; use TestClient for synchronous tests
• Use FastAPI dependencies for shared resources (DB sessions, auth) and close them cleanly
• Add clear error handlers and return proper HTTP status codes and JSON error shapes

Example use cases

• Scaffold a new API with routers for users and items and include them in main.py
• Add OAuth2PasswordBearer token endpoint and secure /users/me with dependency injection
• Replace ad-hoc validation with Pydantic models and descriptive Field constraints
• Add a CORS middleware and a request timing middleware for observability
• Implement background email sending with BackgroundTasks and a file-based log task