FastAPI中使用Pydantic模型定义查询参数及添加标题描述

问题背景 #

要创建/services?status=New接口，status参数仅支持New或Old两个值。最初尝试用Query绑定Pydantic模型时触发AssertionError: Param: status can only be a request body, using Body()错误，改用Depends()后接口可正常运行，但不清楚如何为查询参数添加标题（title）和描述（description）。

报错原因 #

Query用于定义单个查询参数，直接传入Pydantic模型会让FastAPI误认为你要将模型作为请求体解析，因此抛出错误。

解决方案：给Pydantic模型字段添加元数据 #

在Pydantic模型的字段中使用Field来定义标题、描述等元数据，FastAPI会自动将这些信息同步到接口文档（Swagger/Redoc）中，同时保留Depends()的用法。

修改后的完整代码：

from fastapi import APIRouter, Depends
from pydantic import BaseModel, Field
from enum import Enum

router = APIRouter()

class ServiceStatusEnum(str, Enum):
    new = "New"
    old = "Old"

class ServicesQueryParam(BaseModel):
    status: ServiceStatusEnum = Field(
        ...,
        title="服务状态",
        description="筛选服务的状态，仅支持New（新建）或Old（已存在）"
    )

@router.get("/services")
def get_services(q: ServicesQueryParam = Depends()):
    # 业务逻辑中可通过q.status获取参数值
    return {"filtered_status": q.status}

补充说明 #

• Field支持为模型字段添加丰富元数据，包括标题、描述、默认值、校验规则等
• 接口文档会自动展示这些元数据，方便前端或调用方查看参数说明
• 若需添加多个查询参数，直接在ServicesQueryParam模型中新增对应字段即可，无需逐个定义Query

内容的提问来源于stack exchange，提问作者Amin Ba