如何在FastAPI中直接接收非原始类型作为查询参数？

你可以通过以下两种方式让FastAPI自动将JSON格式的查询参数解析为你的Pydantic模型实例，同时完善Swagger文档：

方法一：使用Annotated结合验证器 #

直接在参数注解中添加JSON解析逻辑，让FastAPI自动完成转换：

from fastapi import Query, APIRouter
from pydantic import BaseModel, BeforeValidator
from typing import Annotated, List, Dict

router = APIRouter()

class SomeOtherPydanticType(BaseModel):
    # 定义你的嵌套模型字段
    example_field: str

class MyParam(BaseModel):
    param1: List[str]
    param2: Dict[str, SomeOtherPydanticType]

@router.get("/my/route")
def get_vhist_snap_pnl(
    param: Annotated[
        MyParam,
        BeforeValidator(lambda json_str: MyParam.model_validate_json(json_str)),
        Query(..., description="JSON编码的参数对象")
    ]
) -> str:
    # 此时param已经是MyParam的实例，可直接使用
    print(param.param1)
    print(param.param2["key"].example_field)
    return 'hello world'

方法二：使用依赖项Depends #

创建一个专门的解析函数，通过Depends注入到路由参数中：

from fastapi import Query, APIRouter, Depends
from pydantic import BaseModel
from typing import List, Dict

router = APIRouter()

class SomeOtherPydanticType(BaseModel):
    example_field: str

class MyParam(BaseModel):
    param1: List[str]
    param2: Dict[str, SomeOtherPydanticType]

def parse_my_param(param_str: str = Query(..., description="JSON编码的参数对象")) -> MyParam:
    return MyParam.model_validate_json(param_str)

@router.get("/my/route")
def get_vhist_snap_pnl(
    param: MyParam = Depends(parse_my_param)
) -> str:
    # param已自动解析为MyParam实例
    return 'hello world'

说明 #

• 两种方式都能让Swagger文档正确识别该查询参数，显示你设置的描述，同时FastAPI会自动完成JSON字符串到Pydantic模型的转换，无需手动实例化。
• 注意将原代码中的pydantic.BaseClass改为pydantic.BaseModel，这是Pydantic模型的正确基类。

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