FastAPI如何将查询参数分组放入可折叠菜单优化接口文档

1. 核心原理 #

FastAPI 默认使用的Swagger UI 支持通过 OpenAPI 自定义扩展字段 x-groupParameters 实现参数分组，分组后的参数会自动渲染为可折叠的独立菜单，完全匹配你的需求。

2. 改造generate_params函数 #

你不需要改动原有参数生成逻辑，只需要在返回配置中新增分组规则即可，示例代码如下：

from typing import List, Dict
from pydantic import BaseModel

def generate_params(schema: BaseModel) -> Dict:
    # 此处保留你原有生成参数的逻辑，得到所有符合OpenAPI规范的参数列表
    all_params = 你原有逻辑生成的参数列表

    # 新增：按前缀分类参数
    red_params = []
    green_params = []
    blue_params = []
    other_params = []
    for param in all_params:
        param_name = param["name"]
        if param_name.startswith("RED_"):
            red_params.append(param)
        elif param_name.startswith("GREEN_"):
            green_params.append(param)
        elif param_name.startswith("BLUE_"):
            blue_params.append(param)
        else:
            other_params.append(param)
    
    # 合并最终参数列表，顺序可根据需求调整
    final_params = red_params + green_params + blue_params + other_params

    # 新增：定义参数分组配置
    groups = [
        {
            "name": "红色系参数",
            "parameters": [p["name"] for p in red_params],
            "defaultExpanded": False # 配置默认是否展开，False为默认折叠
        },
        {
            "name": "绿色系参数",
            "parameters": [p["name"] for p in green_params],
            "defaultExpanded": False
        },
        {
            "name": "蓝色系参数",
            "parameters": [p["name"] for p in blue_params],
            "defaultExpanded": False
        }
    ]

    #  返回配置，新增分组扩展字段
    return {
        "parameters": final_params,
        "x-groupParameters": groups
    }

3. 接口定义保持不变 #

原有接口代码不需要做任何调整，继续按原有方式使用openapi_extra即可：

@app.get("/COLORS/", openapi_extra=generate_params(schemas.COLORS))
async def colors(request: Request):
    return handle_request()

4. 效果验证 #

启动服务后打开Swagger UI（默认地址为http://你的服务地址/docs），即可看到三个前缀对应的参数分别在独立的可折叠菜单中，未分组的其他参数会默认展示在公共区域。

适配说明 #

如果你使用的是Redoc文档而非默认的Swagger UI，只需要把分组配置改为给每个参数新增x-group字段即可，示例：param["x-group"] = "红色系参数"，Redoc会自动按该字段对参数做可折叠分组。

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