timothywarner/copilot-dev/api-endpoint-generator

import { Router, Request, Response, NextFunction } from 'express';
import { z } from 'zod';
// --- 1. Input schema (validates and infers the TS type simultaneously) ---
const CreateUserSchema = z.object({
  email: z.string().email({ message: 'Must be a valid email address' }),
  name: z.string().min(2).max(100),
  age: z.number().int().min(0).max(150),
});
// Infer the TypeScript type from the schema — single source of truth
type CreateUserInput = z.infer<typeof CreateUserSchema>;
// --- 2. Response type ---
interface UserResponse {
  id: string;
  email: string;
  name: string;
  createdAt: string;
}
// --- 3. Route handler ---
/**
 * POST /users
 *
 * Creates a new user account.
 *
 * @param req.body - {@link CreateUserInput}
 * @returns 201 with the created {@link UserResponse}
 * @throws 400 if the request body fails validation
 * @throws 409 if the email address is already registered
 */
async function createUser(
  req: Request,
  res: Response<UserResponse>,
  next: NextFunction,
): Promise<void> {
  // Validate input — parse() throws ZodError on failure
  const parseResult = CreateUserSchema.safeParse(req.body);
  if (!parseResult.success) {
    // RFC 7807 Problem Details — consistent error envelope
    res.status(400).json({
      type: 'https://errors.myapp.com/validation-error',
      title: 'Validation Error',
      status: 400,
      detail: 'One or more fields failed validation.',
      errors: parseResult.error.flatten().fieldErrors,
    } as any);
    return;
  }
  // parseResult.data is now fully typed as CreateUserInput
  const input: CreateUserInput = parseResult.data;
  try {
    // Replace with your actual service/repository call
    const user = await userService.create(input);
    // Return immutable response — never mutate the entity object directly
    res.status(201).json({
      id: user.id,
      email: user.email,
      name: user.name,
      createdAt: user.createdAt.toISOString(),
    });
  } catch (error) {
    // Delegate unexpected errors to Express error middleware
    next(error);
  }
}
// --- 4. Router registration ---
export const userRouter = Router();
userRouter.post('/', createUser);

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, EmailStr, Field, field_validator
from uuid import UUID, uuid4
from datetime import datetime, timezone
router = APIRouter(prefix="/users", tags=["users"])
# --- 1. Request schema (Pydantic v2) ---
class CreateUserRequest(BaseModel):
    """Request body for creating a new user."""
    email: EmailStr
    name: str = Field(min_length=2, max_length=100)
    age: int = Field(ge=0, le=150)
    @field_validator("name")
    @classmethod
    def name_must_not_be_blank(cls, value: str) -> str:
        if not value.strip():
            raise ValueError("Name must not be blank or whitespace only")
        return value.strip()
# --- 2. Response schema ---
class UserResponse(BaseModel):
    """Response body returned after creating a user."""
    id: UUID
    email: str
    name: str
    created_at: datetime
# --- 3. Route handler ---
@router.post(
    "/",
    response_model=UserResponse,
    status_code=status.HTTP_201_CREATED,
    summary="Create a new user account",
    responses={
        409: {"description": "Email address already registered"},
    },
)
async def create_user(payload: CreateUserRequest) -> UserResponse:
    """
    Create a new user account.
    - **email**: Must be a valid email address and unique in the system
    - **name**: Between 2 and 100 characters
    - **age**: Between 0 and 150
    """
    # FastAPI validates payload automatically via Pydantic — 422 on failure
    try:
        # Replace with your actual service/repository call
        created = await user_service.create(
            email=payload.email,
            name=payload.name,
            age=payload.age,
        )
    except DuplicateEmailError as exc:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=f"Email '{payload.email}' is already registered.",
        ) from exc
    # Return an immutable response model — Pydantic serializes it
    return UserResponse(
        id=created.id,
        email=created.email,
        name=created.name,
        created_at=created.created_at,
    )

{
  "type": "https://errors.myapp.com/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation.",
  "errors": {
    "email": ["Must be a valid email address"],
    "age": ["Must be between 0 and 150"]
  }
}