FastAPI中覆盖自动生成参数并自定义Swagger UI查询参数文档的方法

方案1：动态生成Pydantic模型结合Depends（推荐） #

该方案符合FastAPI原生设计逻辑，除了自动生成文档外，还自带参数类型校验、默认值填充能力，无需手动处理参数类型转换。
操作步骤如下：

1. 从你的配置文件中读取当前端点对应的所有查询参数的名称、类型、默认值、描述等信息
2. 用Pydantic的create_model方法动态生成查询参数模型
3. 端点参数通过Depends引入该模型即可

代码示例：

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

app = FastAPI()

# 模拟从配置文件读取的参数配置
params_config = [
    {"name": "RED_darker", "type": int, "description": "红色加深数值，范围0-100", "default": 0},
    {"name": "BLUE_lighter", "type": int, "description": "蓝色加亮数值，范围0-100", "default": 0},
    {"name": "GREEN_inverse", "type": bool, "description": "是否反转绿色通道", "default": False},
]

# 动态生成Pydantic模型
fields = {}
for param in params_config:
    fields[param["name"]] = (
        param["type"], 
        Field(default=param["default"], description=param["description"])
    )
ColorAdjustParams = create_model("ColorAdjustParams", **fields)

# 端点定义
@app.get("/ADJUST_COLOR/")
def query_COLORS(params: ColorAdjustParams = Depends()):
    # 可以直接转成字典传给原有处理逻辑
    return look_through_parameters(params.dict())

如果有大量端点需要批量生成，你可以在循环注册每个端点的时候，为每个端点单独生成对应的参数模型，完全适配配置驱动的场景。

方案2：手动注入OpenAPI参数定义（无侵入改造） #

如果你不想修改现有的接收Request、手动解析参数的逻辑，可以直接在路径操作的配置中注入OpenAPI参数定义，Swagger UI会直接读取该配置展示参数，业务逻辑无需任何改动。
代码示例：

from fastapi import FastAPI, Request

app = FastAPI()

# 模拟从配置文件生成的OpenAPI参数格式配置
openapi_params = [
    {
        "name": "RED_darker",
        "in": "query",
        "required": False,
        "description": "红色加深数值，范围0-100",
        "schema": {"type": "integer"}
    },
    {
        "name": "BLUE_lighter",
        "in": "query",
        "required": False,
        "description": "蓝色加亮数值，范围0-100",
        "schema": {"type": "integer"}
    },
    {
        "name": "GREEN_inverse",
        "in": "query",
        "required": False,
        "description": "是否反转绿色通道",
        "schema": {"type": "boolean"}
    }
]

@app.get(
    "/ADJUST_COLOR/",
    openapi_extra={"parameters": openapi_params}
)
def query_COLORS(request: Request):
    return look_through_parameters(request.query_params)

适用场景说明 #

• 方案1适合还在开发阶段、或者需要对参数做合法性校验的场景，原生支持参数校验、类型转换，后续维护成本更低
• 方案2适合已经完成业务逻辑开发、仅需要补全Swagger文档的场景，改造成本几乎为0，完全不侵入原有代码

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