FastAPI如何将任意属性字典映射到Pydantic模型让Swagger展示响应详情

解决方案 #

分层定义Pydantic模型即可适配该动态键的响应结构，同时支持对采购订单ID的格式做正则校验，Swagger会自动识别并展示完整结构：

1. 模型定义（适配Pydantic v2，FastAPI当前官方默认配套版本）

from pydantic import BaseModel, RootModel, Pattern
from typing import List

# 定义单个商品的结构模型
class ProductItem(BaseModel):
    product_id: str
    product_name: str
    quantity: int

# 定义整个响应结构：键为符合xxxx-xxxxxx格式的采购订单ID，值为对应商品列表
# 不需要校验订单ID格式的话，直接把键的类型写为str即可
SomePydanticModel = RootModel[dict[Pattern(r'^\w{4}-\w{6}$'), List[ProductItem]]]

2. 端点写法修正

FastAPI中指定响应模型的参数为response_model，直接传模型类即可，无需实例化：

@app.post(
    "/your-endpoint-path",
    response_model=SomePydanticModel
)
def my_end_point():
    # 你的原有业务逻辑
    response = {
        # 原有响应数据
    }
    return response

适配Pydantic v1的写法

如果仍在使用Pydantic v1，调整模型定义即可：

from pydantic import BaseModel, Field
from typing import List, Dict

class ProductItem(BaseModel):
    product_id: str
    product_name: str
    quantity: int

class SomePydanticModel(BaseModel):
    __root__: Dict[str, List[ProductItem]]
    # 需要校验订单ID格式的话替换为下面的写法
    # __root__: Dict[Field(regex=r'^\w{4}-\w{6}$'), List[ProductItem]]

完成配置后，Swagger文档会自动识别响应结构，展示商品字段说明、数组结构和订单ID的格式要求。

内容的提问来源于stack exchange，提问作者Pranithan T.