如何为通过dataclass传递的FastAPI查询参数添加描述？

你用标准库dataclass的field添加metadata={'description': ...}没效果，是因为FastAPI将标准dataclass转为Pydantic模型时，不会解析标准field的metadata到OpenAPI文档中。以下是两种可行的解决方法：

方法一：使用Pydantic的dataclass装饰器 #

替换标准库的dataclass为Pydantic提供的版本，这样就能通过Field函数或metadata正确添加描述：

from pydantic.dataclasses import dataclass
from fastapi import FastAPI, Depends
from pydantic import Field

app = FastAPI()

@dataclass
class MyDataclass:
    # 方式1：直接用Pydantic的Field指定描述
    x: str = Field(default=None, description="descr of x")
    
    # 方式2：用metadata（同样生效）
    # x: str = field(default=None, metadata={'description': 'descr of x'})

@app.get("/")
async def root(f: MyDataclass = Depends()):
    return {"message": "Hello World"}

方法二：改用Pydantic BaseModel（推荐） #

FastAPI原生对BaseModel支持更完善，直接定义模型类更直观：

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

app = FastAPI()

class MyParams(BaseModel):
    x: str = Field(default=None, description="descr of x")

@app.get("/")
async def root(f: MyParams = Depends()):
    return {"message": "Hello World"}

两种方法都能让参数x的描述正常显示在Swagger UI的自动文档中。

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