FastAPI：如何为基于类的请求参数/过滤器字段添加描述？

完全可以实现为Pydantic模型内的单个字段添加SwaggerUI描述，核心是利用Pydantic的Field类定义字段元数据，再通过FastAPI的Depends正确注入模型作为查询参数，具体步骤如下：

1. 用Pydantic Field定义字段描述 #

在你的MyFilter模型中，给需要添加描述的字段使用Field类，传入description参数即可。示例代码：

from pydantic import BaseModel, Field
from fastapi import FastAPI, Depends

app = FastAPI()

class MyFilter(BaseModel):
    include_documents: bool = Field(
        default=False,
        description="控制返回结果是否包含关联的文档数据"
    )
    page_index: int = Field(
        default=1,
        description="分页查询的页码，从1开始"
    )
    keyword: str | None = Field(
        default=None,
        description="用于模糊匹配内容的关键词"
    )

2. 正确通过Depends注入模型 #

不需要用Query或Path包裹整个模型，直接在接口参数中使用Depends()注入MyFilter即可。如果是GET接口，FastAPI会自动将模型字段解析为URL查询参数，同时SwaggerUI会同步显示每个字段的描述：

@app.get("/api/list/")
async def get_result_list(my_filter: MyFilter = Depends()):
    # 这里处理过滤逻辑
    return {"filter_params": my_filter.dict(), "data": []}

3. 解决"只能作为请求体"的报错 #

你之前遇到的报错，是因为如果在POST接口中直接注入Pydantic模型，FastAPI默认会将其解析为请求体。如果需要在POST接口中把模型作为查询参数使用，可以通过Annotated结合Depends显式声明：

from typing import Annotated

@app.post("/api/list/")
async def post_result_list(my_filter: Annotated[MyFilter, Depends()]):
    return {"filter_params": my_filter.dict(), "data": []}

此时SwaggerUI仍会正确显示每个字段的描述，且参数会被解析为查询参数而非请求体。

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