使用 Pydantic 模型 (FastAPI) 在 swagger 文档中设置查询参数的描述答案

【问题标题】：Set description for query parameter in swagger doc using Pydantic model (FastAPI)使用 Pydantic 模型 (FastAPI) 在 swagger 文档中设置查询参数的描述
【发布时间】：2025-12-16 01:20:03
【问题描述】：

这是继续question。

我添加了一个模型来获取 pydantic 模型的查询参数

class QueryParams(BaseModel):
    x: str = Field(description="query x")
    y: str = Field(description="query y")
    z: str = Field(description="query z")


@app.get("/test-query-url/{test_id}")
async def get_by_query(test_id: int, query_params: QueryParams = Depends()):
    print(test_id)
    print(query_params.dict(by_alias=True))
    return True

它按预期工作，但描述（在模型中添加）没有反映在 swagger ui 中

但是如果请求体使用相同的模型，那么描述以swagger显示

在 swagger ui 中我是否遗漏了什么来获取 QueryParams(model) 的描述？

【问题讨论】：

我不同意 Arakkabal 的回答，我能够做到这一点，OpenAPI Spec & Swagger 也允许这样做，并且查询参数有一个描述字段 see。所以这意味着你应该这样做，因为 FastAPI 是基于 OpenAPI 规范。今天晚些时候我会再看看这个。
谢谢，如果您有任何发现请告诉我

标签： python fastapi

【解决方案1】：

Pydantic 模型无法做到这一点

获得所需结果的解决方法是使用 自定义依赖类（或函数），而不是 Pydantic 模型

from fastapi import Depends, FastAPI, Query

app = FastAPI()


class CustomQueryParams:
    def __init__(
        self,
        foo: str = Query(..., description="Cool Description for foo"),
        bar: str = Query(..., description="Cool Description for bar"),
    ):
        self.foo = foo
        self.bar = bar


@app.get("/test-query/")
async def get_by_query(params: CustomQueryParams = Depends()):
    return params

因此，您将拥有文档，

参考文献

Validate GET parameters in FastAPI--(FastAPI GitHub) 似乎对扩展 Pydantic 模型以验证 GET 参数的兴趣不大
Classes as Dependencies--(FastAPI Doc)

【讨论】：

这样就可以了。但想拥有 pydantic 模型
Pydantic 无法做到这一点。 ref this
不知道为什么要使用 Query，它具有与 pydantic Field 相似的属性
Query(...) 用于生成 OpenAPI 架构

【解决方案2】：

这对我有用


from fastapi import Depends, FastAPI, Query

@app.post("/route")
def some_api(
        self,
        query_param_1: float = Query(None, description="description goes here", ),
        query_param_2: float = Query(None, description="Param 2 does xyz"),
):
    
return "hello world"

【讨论】：