Cursor rule: FastAPI routers & schemas

An auto-attached .mdc rule for router/schema hygiene: explicit response_model, edge validation, and a full path-operation example.

---
description: FastAPI router and Pydantic schema conventions
globs: app/api/**/*.py,app/schemas/**/*.py
alwaysApply: false
---

# Router and schema rules

- Routers declare `response_model` explicitly; return schema instances, not ORM
  models. Serialization surprises come from skipping this.
- Every route gets auth via the `CurrentUser` dependency unless it is in the
  public list in `app/api/public.py`.
- Path operations stay under ~30 lines; push logic into `app/services/`.
- Request schemas validate at the edge:

```python
class OrderCreate(BaseModel):
    sku: str = Field(min_length=1, max_length=64)
    quantity: int = Field(gt=0, le=1000)

@router.post("/orders", response_model=OrderRead, status_code=201)
async def create_order(
    body: OrderCreate,
    user: CurrentUser,
    session: AsyncSession = Depends(get_session),
) -> OrderRead:
    return await orders_service.create(session, user, body)
```

- Follow @app/api/orders.py for pagination, error mapping, and dependency order.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.