FastAPI路径参数加描述引发422错误及文档失效问题求助

直接用Annotated + Path的组合写法就能解决你的问题，这是FastAPI 0.95.0+版本官方推荐的标准用法，完美适配你的0.104.1版本：

from fastapi import FastAPI, Path
from typing import Annotated

app = FastAPI()

@app.get("/api/v1/book/{id}")
def get_book(id: Annotated[str, Path(..., description="The book ID to retrieve")]):
    return {"book_id": id}

为什么之前的写法出问题 #

• 直接写id: str = Path(...)：在新版本FastAPI中，这种赋值式写法会被框架误判参数类型，导致路径参数无法被正确解析，所以返回422错误提示id缺失。
• 错误的Annotated写法：如果只写id: Annotated[str, ...]或者没把Path对象放进Annotated的元数据里，框架就无法读取参数描述，自然不会在文档中显示。

验证效果 #

写完上面的代码后，访问自动文档页面（/docs），你会看到id参数的描述正常显示；调用/api/v1/book/xxx接口时，也能正确获取路径参数，不会再返回422错误。

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