FastAPI如何同时实现Depends依赖校验与Body参数Swagger描述？

有三种可行方案可以同时实现自定义依赖校验，并保留Swagger UI中的参数描述：

方案一：使用Annotated结合Body与Depends（推荐，FastAPI 0.95+支持） #

将原有的Body元数据和Depends校验逻辑通过Annotated组合，既保留参数描述，又执行校验逻辑：

from typing import Annotated
from fastapi import Body, Depends, HTTPException, APIRouter
from pydantic import BaseModel

router = APIRouter()

class DeleteItemParams(BaseModel):
    item_id: int
    # 若需字段级描述，可在此用Field添加，例如：item_id: int = Field(..., description="待删除的项目ID")

# 保留原有的Body描述配置
DeleteItemParamsMetadata = Body(
    None, 
    description="my verbose description that will appear on swaggerui under the schema of this parameter"
)

def validate_param(param: DeleteItemParams):
    # 自定义复杂校验逻辑
    if param.item_id <= 0:
        raise HTTPException(status_code=422, detail="Invalid item ID")
    # 可选：修改参数
    param.item_id *= 2
    return param

@router.post("/myendpoint")
async def delete_objects(
    param: Annotated[DeleteItemParams, DeleteItemParamsMetadata, Depends(validate_param)]
):
    return {"processed_param": param}

方案二：在Pydantic模型中添加描述 #

如果参数描述是针对整个请求模型的，直接在模型的配置中添加描述，Swagger会自动读取该描述：

from fastapi import Depends, HTTPException, APIRouter
from pydantic import BaseModel, ConfigDict

router = APIRouter()

class DeleteItemParams(BaseModel):
    # 模型级描述，会在Swagger的Schema中显示
    model_config = ConfigDict(
        description="my verbose description that will appear on swaggerui under the schema of this parameter"
    )
    item_id: int

def validate_param(param: DeleteItemParams):
    if param.item_id <= 0:
        raise HTTPException(status_code=422, detail="Invalid item ID")
    param.item_id *= 2
    return param

@router.post("/myendpoint")
async def delete_objects(param: DeleteItemParams = Depends(validate_param)):
    return {"processed_param": param}

方案三：在依赖函数的参数中指定Body描述 #

将原有的Body配置直接移到依赖函数的参数定义上，让依赖函数同时负责参数解析和校验：

from fastapi import Body, Depends, HTTPException, APIRouter
from pydantic import BaseModel

router = APIRouter()

class DeleteItemParams(BaseModel):
    item_id: int

def validate_param(
    param: DeleteItemParams = Body(
        None, 
        description="my verbose description that will appear on swaggerui under the schema of this parameter"
    )
):
    if param.item_id <= 0:
        raise HTTPException(status_code=422, detail="Invalid item ID")
    param.item_id *= 2
    return param

@router.post("/myendpoint")
async def delete_objects(param: DeleteItemParams = Depends(validate_param)):
    return {"processed_param": param}

方案选择建议 #

• 方案一：最灵活，适合需要复用原有Body配置（如描述、示例、额外校验规则）的场景。
• 方案二：符合Pydantic的设计规范，适合描述属于模型本身、需在多个接口共享的场景。
• 方案三：改造成本最低，适合快速调整单个接口的场景。

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