FastAPI：向基于类的请求参数/过滤器添加描述答案

【问题标题】：FastAPI: Add description to a class based request parameter / filterFastAPI：向基于类的请求参数/过滤器添加描述
【发布时间】：2022-08-15 22:30:43
【问题描述】：

我正在使用这个模型类，它指定了可以用来过滤端点结果列表的不同输入参数：

from pydantic import BaseModel

class MyFilter(BaseModel):
    status: Optional[ValidationStatus]
    reference: Optional[str]
    include_documents: Optional[bool]

与我的输入模型字段相同，我想将描述字符串添加到 SwaggerUI 以解释含义，例如专门针对include_documents。

我的端点看起来像：

def get_list(
    request: Request, my_filter: MyFilter = Depends(), db: Session = Depends(get_db)
):

我在文档中只看到可以使用Query 对整体参数进行描述，但不能对模型中的每个“字段”进行描述。那可能吗？

当我在方法签名中尝试 Query 或 Path 时，我收到错误消息：Param: my_filter can only be a request body, using Body()

您是否已经检查过文档？ fastapi.tiangolo.com/tutorial/body-fields 是这样吗？
@Isabi 如果我对 Body() 理解正确，则需要在请求正文中发送参数，而我希望它们是 url 参数，例如 ?include_documents=true

标签： python swagger-ui fastapi pydantic

【解决方案1】：

为了在OpenAPI 中记录query parameters，有一个额外的部分专门用于这部分

https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata

必须使用 Query 对象。使用参数title 和description，将向API 的使用者提供必要的文档。

这是取自官方文档的 python 3.10 示例。

from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: str
    | None = Query(
        default=None,
        title="Query string",
        description="Query string for the items to search in the database that have a good match",
        min_length=3,
    )
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

2022 年 12 月 8 日更新好吧，我没有得到确切的问题。评论后，现在我明白了。

思路是一样的，只适用于https://fastapi.tiangolo.com/tutorial/body-fields/#import-field中描述的pydantic模型

这里的例子取自文档

class Item(BaseModel):
    name: str
    description: str | None = Field(
        default=None, title="The description of the item", max_length=300
    )
    price: float = Field(gt=0, description="The price must be greater than zero")
    tax: float | None = None

【讨论】：

我在文档中看到了这个例子，但它只显示了它是如何针对单个参数完成的，而不是像我的问题中那样的过滤器模型。
@djangonaut 查看更新的答案
感谢您的帮助，但Body() 用于要求请求正文数据，而不是用于指定 url 参数。
您正在使用 GET 请求。那么不，不可能有一个pydantic模型作为GET参数。您可以编写一个dependency 注入来读取数据，然后将其填充到 pydantic 模型中。否则我没有头绪

【解决方案2】：

我在 fastapi 的 github 问题中找到了解决方案/解决方法：https://github.com/tiangolo/fastapi/issues/4700

这对我有用：

from fastapi import Query

class MyFilter(BaseModel):
    include_documents: Optional[bool] = Query(Query(description="hello"))

【讨论】：