FastAPI递归响应模型导致API文档崩溃问题求助

问题根源 #

递归模型生成OpenAPI文档时，需要Pydantic正确解析类型引用。单纯靠from __future__ import annotations延迟类型解析，无法让FastAPI的文档生成器正确识别递归结构，最终导致渲染崩溃。

正确解决步骤 #

1. 用ForwardRef显式定义递归字段 #

不要直接在children字段里写list[Category]，改用ForwardRef或字符串形式的类型注解，同时在类定义完成后手动触发模型重建：

from __future__ import annotations
from pydantic import BaseModel, ForwardRef
from fastapi import FastAPI

# 提前声明递归引用
CategoryRef = ForwardRef("Category")

class Category(BaseModel):
    title: str
    category_id: int
    category_path: str
    # 用ForwardRef或字符串"list[Category]"定义，同时设为可选避免无限递归
    children: list[CategoryRef] | None = None

# 必须在类定义后调用该方法，解析递归引用
Category.model_rebuild()

app = FastAPI()

@app.get("/categories", response_model=list[Category])
async def get_categories():
    # 示例返回数据
    return [
        {
            "title": "根分类",
            "category_id": 1,
            "category_path": "/1",
            "children": [
                {
                    "title": "子分类",
                    "category_id": 2,
                    "category_path": "/1/2",
                    "children": None
                }
            ]
        }
    ]

2. 关键注意事项 #

• 给children字段设置默认值（如None或空列表），避免文档生成器陷入无限类型解析循环。
• 确保model_rebuild()在类定义完成后调用，且早于任何引用该模型的接口定义。
• 若使用Pydantic v2，model_rebuild用法与v1一致，但需注意多模型依赖时的重建顺序。

3. 排查常见失效原因 #

如果之前尝试ForwardRef没解决问题，检查以下几点：

• 是否漏写了model_rebuild()调用？
• children字段是否设为必填？必填递归字段会触发无限解析。
• ForwardRef里的类名字符串是否和实际类名拼写一致？

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