Cursor-Driven Development in FastAPI: Using AI to Generate Type-Safe API Schemas and Catch Contract Breaks Before Deployment

API contracts break silently. Your React 19 frontend calls POST /users expecting { id: string; email: string }, but your FastAPI backend shipped { userId: number; userEmail: string }. The request succeeds. The response doesn't match. Your frontend crashes in production, and you spend three hours in an incident call figuring out why a perfectly typed TypeScript component is receiving undefined properties.

I've lived this exact nightmare twice on CitizenApp—once before we shipped, once after. The second time cost us a customer's trust and three hours of developer velocity.

The fix isn't better testing or more code review. It's treating your API contract as the single source of truth and using Claude to generate both sides of it from natural language specifications, then validating that they match in CI before deployment. This is cursor-driven development done right: not mindless boilerplate generation, but intelligent contract enforcement that catches type mismatches across language boundaries.

Why This Matters More Than You Think

Most full-stack developers reach for AI to generate TypeScript components or FastAPI route handlers. That's fine. But the real power is forcing your frontend and backend to negotiate a contract before either side exists. When you do this correctly:

Type safety propagates both directions. A TypeScript type change doesn't silently break your Python backend.
Breaking changes fail CI, not production. You catch the moment a contract changes before it ships.
Documentation is generated, not written. Your API spec is always in sync because it's the source of truth.
Onboarding new developers becomes faster. They read the natural language spec, see the contract, and understand the system without hunting through six Slack threads.

I prefer this approach because it forces discipline. Too many teams use AI as a shortcut to avoid thinking about their API design. This pattern does the opposite: it requires you to think first, validate second.

The Pattern: Spec → Contract → Validation

Here's how it works on CitizenApp:

Write a natural language specification (plain English).
Ask Claude to generate a Pydantic schema + FastAPI route stub.
Ask Claude to generate a matching TypeScript type + React hook for that endpoint.
Add a CI step that validates the TypeScript types match the Pydantic schema via introspection.
If they don't match, the build fails. Deliberately.

Let's build this end-to-end.

Step 1: The Natural Language Spec

Feature: User Profile Update
Description: Allow authenticated users to update their profile metadata.
Fields: firstName (string, required), lastName (string, required), bio (string, optional, max 500 chars)
Validation: firstName and lastName must be at least 2 characters
Response: Returns updated user object with id, email, firstName, lastName, bio, updatedAt
Auth: Requires valid JWT in Authorization header

This goes in a file: specs/user-profile-update.md

Step 2: Claude Generates the Backend Contract

Prompt your Cursor AI agent (or use Anthropic's API directly):

Given this spec, generate a FastAPI route with Pydantic schema. 
Use SQLAlchemy ORM patterns. 
Include validation decorators.
Output ONLY Python code, no explanation.

[paste spec here]

Claude outputs something like:

# schemas.py
from pydantic import BaseModel, Field, field_validator

class UserProfileUpdateRequest(BaseModel):
    firstName: str = Field(..., min_length=2, max_length=100)
    lastName: str = Field(..., min_length=2, max_length=100)
    bio: str | None = Field(None, max_length=500)

    @field_validator("firstName", "lastName")
    @classmethod
    def validate_names(cls, v):
        return v.strip()

class UserProfileResponse(BaseModel):
    id: str
    email: str
    firstName: str
    lastName: str
    bio: str | None
    updatedAt: str  # ISO 8601

    class Config:
        from_attributes = True

# routes.py
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from .schemas import UserProfileUpdateRequest, UserProfileResponse
from .db import get_db
from .auth import get_current_user

router = APIRouter()

@router.put("/users/profile", response_model=UserProfileResponse)
async def update_user_profile(
    request: UserProfileUpdateRequest,
    current_user = Depends(get_current_user),
    db: Session = Depends(get_db),
):
    user = db.query(User).filter(User.id == current_user.id).first()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")

    user.firstName = request.firstName
    user.lastName = request.lastName
    if request.bio is not None:
        user.bio = request.bio

    db.commit()
    db.refresh(user)
    return user

You review this, tweak it if needed, and commit it. This is now your source of truth.

Step 3: Claude Generates the Frontend Contract

Different prompt:

Given this API spec and the Pydantic schemas below, generate:
1. TypeScript types matching the schemas (use zod or ts-pattern if validation needed)
2. A React 19 hook using useAsync or similar pattern

Use TanStack Query for mutations if appropriate.
Assume JWT is in Authorization header (handled by interceptor).

Pydantic schema:
[paste schema here]

API spec:
[paste spec here]

Claude outputs:

// types/user.ts
export interface UserProfileUpdateRequest {
  firstName: string;
  lastName: string;
  bio?: string;
}

export interface UserProfileResponse {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  bio?: string;
  updatedAt: string;
}

// hooks/useUpdateUserProfile.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";

export function useUpdateUserProfile() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (
      data: UserProfileUpdateRequest
    ): Promise<UserProfileResponse> => {
      const response = await fetch("/api/users/profile", {
        method: "PUT",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${localStorage.getItem("token")}`,
        },
        body: JSON.stringify(data),
      });

      if (!response.ok) {
        throw new Error(`Failed to update profile: ${response.statusText}`);
      }

      return response.json();
    },
    onSuccess: (data) => {
      queryClient.setQueryData(["user"], data);
    },
  });
}

Step 4: Contract Validation in CI

This is where the magic happens. Create a Python script that introspects both:

# scripts/validate_contracts.py
import json
import subprocess
import sys
from typing import Any

def get_pydantic_schema(module_path: str, class_name: str) -> dict[str, Any]:
    """Extract JSON schema from Pydantic model"""
    import importlib.util
    spec = importlib.util.spec_from_file_location("module", module_path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    model_class = getattr(module, class_name)
    return model_class.model_json_schema()

def get_typescript_types(file_path: str) -> dict[str, Any]:
    """Parse TypeScript types using TypeScript compiler API"""
    result = subprocess.run(
        ["npx", "ts-json-schema-generator", "--path", file_path, "--type", "*"],
        capture_output=True,
        text=True,
    )
    return json.loads(result.stdout)

def validate_contract(python_schema: dict, ts_schema: dict) -> bool:
    """Ensure Python and TypeScript schemas match"""
    py_props = python_schema.get("properties", {})
    ts_props = ts_schema.get("properties", {})

    # Check all Python props exist in TypeScript
    for key, py_prop in py_props.items():
        if key not in ts_props:
            print(f"❌ Missing in TypeScript: {key}")
            return False

        # Map Python types to TypeScript
        py_type = py_prop.get("type")
        ts_type = ts_props[key].get("type")
        if py_type != ts_type:
            print(f"❌ Type mismatch for {key}: Python={py_type}, TS={ts_type}")
            return False

    return True

if __name__ == "__main__":
    py_schema = get_pydantic_schema("app/schemas.py", "UserProfileUpdateRequest")
    ts_schema = get_typescript_types("src/types/user.ts")

    if not validate_contract(py_schema, ts_schema):
        sys.exit(1)

    print("✅ Contract validated")

Add this to your GitHub Actions workflow:

- name: Validate API contracts
  run: python scripts/validate_contracts.py

- name: Run tests
  run: pytest app/ && npm test

Now, if someone changes a Pydantic field from str to int without updating the TypeScript type, the build fails before merging. This has saved us countless production incidents.

Gotcha: Schema Drift in Optional Fields

This burned me hard: I made a field optional in Pydantic (bio: str | None) but forgot to mark it optional in TypeScript (bio: string instead of bio?: string). The validation passed because my naive script only checked required fields.

The fix: validate both presence and optionality:


python
def validate_contract(python_schema: dict, ts_schema: dict) -> bool:
    py_required = set(python_schema.get

推荐订阅源

DEV Community