FastAPI生成的Swagger文档未替换路径参数占位符问题排查

算力阿峰

2026-6-23

问题原因与解决方案

问题根源

你遇到的是FastAPI 0.101.1版本的兼容性问题：当APIRouter的前缀包含路径参数（如user/{user_id}），同时路由自身又定义了路径参数（如/post/{post_id}）时，Swagger UI无法正确识别并填充两个路径参数，只会替换其中一个，另一个保留为URL编码的占位符。

另外你的代码存在笔误：返回语句中的company_id未在函数参数中定义，应该改为user_id，否则运行时会抛出NameError。

解决方案

针对当前版本，有两种可行的解决方式：

方案1：移除APIRouter前缀中的路径参数

将所有路径参数统一放在路由装饰器的路径中，避免前缀包含参数：

from fastapi import APIRouter

api_router = APIRouter()

@api_router.put("/user/{user_id}/post/{post_id}")
def module_deep_clone(
        user_id: int,
        post_id: int,
):
    return {"post_id": post_id, "user_id": user_id}

这种方式下，Swagger UI能正常识别两个路径参数，输入值会正确替换占位符。

方案2：显式使用`Path`标记路径参数

通过Path类显式声明所有路径参数，让FastAPI更精准地生成OpenAPI文档，确保Swagger UI能正确解析：

from fastapi import APIRouter, Path

api_router = APIRouter(prefix="user/{user_id}")

@api_router.put("/post/{post_id}")
def module_deep_clone(
        user_id: int = Path(...),
        post_id: int = Path(...),
):
    return {"post_id": post_id, "user_id": user_id}

显式的参数声明会让OpenAPI文档中参数的定义更清晰，Swagger UI就能正确填充两个路径参数的值。