FastAPI文档中路径参数显示为查询参数的问题及解决

成因 #

FastAPI通过函数签名中的参数声明来识别路径参数。你的代码中，路由函数get_profile没有直接声明customer_id参数，而是通过Depends依赖项获取数据。FastAPI无法从函数签名中感知到路径参数的存在，因此将依赖逻辑中涉及的参数默认识别为查询参数。

解决方法 #

需要让FastAPI明确感知到路径参数的存在，有两种常用方式：

方式一：路由函数显式声明路径参数并传递给依赖 #

1. 调整依赖方法，接收路径参数：

# models.py 中修改依赖方法
class CustomerProfile:
    @staticmethod
    async def get_profile_or_404(customer_id: int):
        # 根据customer_id查询用户档案的逻辑
        profile = await your_db_query_method(customer_id)
        if not profile:
            raise HTTPException(status_code=404, detail="Not found")
        return profile

2. 修改路由函数，显式声明路径参数并传入依赖：

@router.get(
    "/{customer_id}",
    response_model=schemas.CustomerProfileDetail
)
async def get_profile(
    customer_id: int,
    profile: schemas.CustomerProfileDetail = Depends(models.CustomerProfile.get_profile_or_404)
) -> schemas.CustomerProfileDetail:
    return profile

方式二：依赖方法直接通过Path对象提取路径参数 #

如果不想在路由函数中显式声明参数，可以让依赖方法使用Path对象直接绑定路径参数：

from fastapi import Path

# models.py 中修改依赖方法
class CustomerProfile:
    @staticmethod
    async def get_profile_or_404(customer_id: int = Path(...)):
        # 查询逻辑同上
        ...

# 路由函数无需额外声明参数
@router.get(
    "/{customer_id}",
    response_model=schemas.CustomerProfileDetail
)
async def get_profile(
    profile: schemas.CustomerProfileDetail = Depends(models.CustomerProfile.get_profile_or_404)
) -> schemas.CustomerProfileDetail:
    return profile

两种方式都能让FastAPI正确识别customer_id为路径参数，OpenAPI文档中也会正常显示路径参数输入区域。如果后续需要添加多个路径参数（如/{customer_id}/{order_id}），只需按照相同逻辑添加对应的参数声明即可。

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