FastAPI+Pydantic中数组嵌套模型OpenAPI文档层级丢失问题排查

你这问题核心是Field的用法错误：Field的第一个参数是用来设置字段默认值的，不是用来指定类型的。你把List[MyModel]当成默认值传入Field，反而干扰了FastAPI对类型注解的识别，导致它没法把数组元素关联到MyModel，只能泛化成object。

正确写法示例 #

方式1：类型注解+Field（仅传描述等参数）

from pydantic import BaseModel, Field
from typing import List

class MyModel(BaseModel):
    description: str
    success: bool

class TopLevel(BaseModel):
    message: str
    matches: List[MyModel] = Field(description="An array of matches found")

方式2：用Annotated（Pydantic v2+推荐写法）

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

class MyModel(BaseModel):
    description: str
    success: bool

class TopLevel(BaseModel):
    message: str
    matches: Annotated[List[MyModel], Field(description="An array of matches found")]

如果用的是Pydantic v2，也可以直接用Python原生的list代替List，效果一致：

matches: list[MyModel] = Field(description="An array of matches found")

改完之后，OpenAPI文档里的matches就会显示为array<MyModel>，子项也会保留MyModel的类名和完整结构。

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