Claude Code FastAPI OpenAPI Schema Generation Workflow

FastAPI has become one of the most popular Python frameworks for building modern APIs, largely because it automatically generates OpenAPI documentation from your code. When combined with Claude Code, you can streamline the entire workflow of designing, implementing, and documenting your APIs. This guide shows you how to use Claude Code effectively for FastAPI OpenAPI schema generation.

Understanding FastAPI’s OpenAPI Generation

FastAPI uses Pydantic models to define request and response schemas automatically. When you create endpoint functions with type hints, FastAPI introspects them at runtime to produce a complete OpenAPI specification. This specification can then be used to generate API documentation, client SDKs, and validate API contracts.

The key components that FastAPI uses for schema generation include:

Pydantic models - Define data structures with type annotations
Path operation functions - Your API endpoints with decorated functions
Response models - Specify what the API returns
Field validators - Add constraints and validation rules

Setting Up Your FastAPI Project for Schema Generation

Before using Claude Code for OpenAPI schema generation, ensure your project is properly configured. Create a new FastAPI project with the necessary dependencies:

mkdir fastapi-openapi-project
cd fastapi-openapi-project
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn pydantic

Create a basic FastAPI application with properly typed models:

from fastapi import FastAPI
from pydantic import BaseModel, Field, EmailStr
from typing import Optional, List
from datetime import datetime

app = FastAPI(
    title="User Management API",
    description="API for managing users and their profiles",
    version="1.0.0"
)

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    full_name: Optional[str] = None

class UserResponse(BaseModel):
    id: int
    username: str
    email: EmailStr
    full_name: Optional[str]
    created_at: datetime
    
    class Config:
        from_attributes = True

@app.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate):
    # Implementation here
    pass

@app.get("/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int):
    # Implementation here
    pass

Using Claude Code for Schema-First Development

Schema-first development involves designing your API contract before implementing the logic. Claude Code excels at this workflow by helping you define comprehensive OpenAPI schemas that capture all edge cases and business requirements.

Step 1: Define Your Schema Requirements

When starting a new API endpoint, provide Claude Code with clear requirements:

Create a Pydantic model for an order that includes:
- order_id (string, UUID format)
- customer_id (integer)
- items (list of order items, each with product_id, quantity, unit_price)
- total_amount (decimal with 2 decimal places)
- status (enum: pending, processing, shipped, delivered, cancelled)
- created_at (datetime)
- shipping_address (nested object with street, city, state, zip_code, country)

Claude Code will generate the appropriate Pydantic model with all validation rules:

from pydantic import BaseModel, Field, field_validator
from typing import List, Optional
from decimal import Decimal
from uuid import UUID
from datetime import datetime
from enum import Enum
from uuid import UUID as UUIDType

class OrderStatus(str, Enum):
    pending = "pending"
    processing = "processing"
    shipped = "shipped"
    delivered = "delivered"
    cancelled = "cancelled"

class ShippingAddress(BaseModel):
    street: str = Field(..., min_length=1)
    city: str = Field(..., min_length=1)
    state: str = Field(..., min_length=2)
    zip_code: str = Field(..., pattern=r"^\d{5}(-\d{4})?$")
    country: str = Field(..., min_length=2, max_length=2)

class OrderItem(BaseModel):
    product_id: str
    quantity: int = Field(..., gt=0)
    unit_price: Decimal = Field(..., decimal_places=2)

class Order(BaseModel):
    order_id: UUID
    customer_id: int
    items: List[OrderItem]
    total_amount: Decimal = Field(..., decimal_places=2)
    status: OrderStatus
    created_at: datetime
    shipping_address: ShippingAddress

Step 2: Generate Endpoint Definitions

After defining your models, ask Claude Code to create the corresponding endpoints:

Create FastAPI endpoints for the order management API:
- POST /orders - Create a new order
- GET /orders/{order_id} - Get order by ID
- GET /orders - List orders with pagination (page, limit params)
- PATCH /orders/{order_id}/status - Update order status
- DELETE /orders/{order_id} - Cancel an order

Include proper error responses (404 for not found, 400 for invalid status transitions).

Claude Code will generate the complete endpoint implementations with proper error handling.

Accessing and Using the Generated OpenAPI Schema

FastAPI automatically generates the OpenAPI schema at runtime. You can access it in several ways:

Via the Automatic Docs Endpoint

Start your FastAPI server and visit /docs for the Swagger UI or /redoc for ReDoc documentation. Both are generated from the OpenAPI schema.

Programmatically Access the Schema

To get the raw OpenAPI JSON schema:

from fastapi import FastAPI

app = FastAPI()

# Access the OpenAPI schema
openapi_schema = app.openapi()

# Save to file
import json
with open("openapi.json", "w") as f:
    json.dump(openapi_schema, f, indent=2)

Using the CLI

Generate the OpenAPI schema from the command line:

uvicorn main:app --generate-openapi-schema > openapi.json

Best Practices for Schema Generation with Claude Code

Use Descriptive Field Names and Documentation

Always add docstrings and field descriptions for better auto-generated documentation:

class UserProfile(BaseModel):
    """User profile information."""
    bio: Optional[str] = Field(
        None,
        description="Short biography of the user",
        max_length=500
    )
    avatar_url: Optional[str] = Field(
        None,
        description="URL to the user's avatar image"
    )

Leverage Response Models for Clear API Contracts

Always specify response models to ensure the OpenAPI schema accurately documents your API responses:

@app.get("/users", response_model=List[UserResponse])
async def list_users(limit: int = 100, offset: int = 0):
    """List all users with pagination."""
    users = await fetch_users(limit=limit, offset=offset)
    return users

Use Enums for Constrained Values

Define enums for fields with limited valid values:

from enum import Enum

class UserRole(str, Enum):
    admin = "admin"
    moderator = "moderator"
    user = "user"
    guest = "guest"

class User(BaseModel):
    role: UserRole

This generates proper OpenAPI schema with enum constraints.

Automating Schema Validation

Integrate OpenAPI schema validation into your development workflow:

Generate Client SDKs

Use the OpenAPI schema to generate typed client libraries:

pip install openapi-generator-cli
openapi-generator generate -i openapi.json -g python -o ./client

Contract Testing

Validate that your implementation matches the schema:

pip install pytest-openapi-schema
pytest --validate-schema test_api.py

Common Issues and Solutions

Schema Not Generating Properly

If your OpenAPI schema is incomplete, ensure you’re using Pydantic models with proper type hints. Avoid using Any types when possible, and ensure all nested models are properly imported.

Circular Import Errors

When models span multiple files, organize them properly:

# models/__init__.py
from .user import User, UserCreate
from .order import Order, OrderCreate

__all__ = ["User", "UserCreate", "Order", "OrderCreate"]

Schema Version Compatibility

Ensure your FastAPI and Pydantic versions are compatible. FastAPI 0.100+ requires Pydantic v2.

Actionable Workflow Summary

Define requirements first - Tell Claude Code your data requirements before implementation
Use schema-first approach - Generate Pydantic models before writing endpoint logic
Add validation constraints - Use Field() with min/max values, patterns, and enums
Specify response models - Always declare what your endpoints return
Test the documentation - Visit /docs and /redoc to verify schema accuracy
Generate client SDKs - Use the OpenAPI schema for type-safe API clients

By following this workflow with Claude Code, you can rapidly develop well-documented FastAPI applications with accurate OpenAPI schemas that serve as a single source of truth for your entire API ecosystem.

Built by theluckystrike — More at zovo.one