FastAPI中如何配置可按序选择的枚举列表查询参数？

默认情况下，FastAPI中List[OrderOptions]类型的查询参数在Swagger UI会渲染为多选下拉框，但下拉框是集合类型，无法保留选择顺序，也不允许重复选择同一枚举值。要实现有序、可重复的排序参数选择，有两种可行方案：

方案一：配置Query参数的序列风格 #

通过修改Query的参数配置，让Swagger生成支持顺序输入和重复选择的界面，同时保留枚举的类型校验。

代码示例 #

from enum import Enum
from fastapi import FastAPI, Query
from typing import Optional, List

app = FastAPI()

# 定义排序枚举
class OrderOptions(str, Enum):
    id_asc = "id_asc"
    id_desc = "id_desc"
    name_asc = "name_asc"
    name_desc = "name_desc"

@app.get("/entities/")
async def get_entities(
    custom_order: Optional[List[OrderOptions]] = Query(
        None,
        description="支持按顺序选择排序规则，可重复选择同一规则",
        style="form",
        explode=True,
        allow_duplicates=True
    )
):
    # 这里custom_order会严格保留传入的顺序和重复值
    return {"applied_order": [item.value for item in custom_order]}

配置说明 #

• style="form" + explode=True：让Swagger生成多个独立的参数输入框（可点击"Add item"添加），每个输入框是枚举下拉选项，支持按顺序选择。
• allow_duplicates=True：允许同一枚举值被多次选择。

在Swagger UI中，你可以通过多次点击"Add item"来按顺序添加排序规则，甚至重复选择同一个枚举值，后端接收到的custom_order列表会完全保留输入的顺序。

方案二：使用字符串参数手动解析 #

如果希望更灵活的输入方式（比如直接输入逗号分隔的字符串），可以将参数定义为字符串类型，在后端手动分割并转换为枚举列表。

代码示例 #

from enum import Enum
from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

class OrderOptions(str, Enum):
    id_asc = "id_asc"
    id_desc = "id_desc"
    name_asc = "name_asc"
    name_desc = "name_desc"

@app.get("/entities/")
async def get_entities(
    custom_order: Optional[str] = Query(
        None,
        description="排序规则，用逗号分隔（示例：id_asc,name_desc,id_asc）"
    )
):
    order_list = []
    if custom_order:
        for item_str in custom_order.split(","):
            trimmed_item = item_str.strip()
            try:
                order_list.append(OrderOptions(trimmed_item))
            except ValueError:
                # 处理无效值：可选择忽略或返回错误提示
                continue
    return {"applied_order": [item.value for item in order_list]}

优势 #

• Swagger UI中显示为普通文本输入框，用户可以自由输入逗号分隔的排序规则，完全自定义顺序和重复。
• 无需依赖FastAPI的参数渲染逻辑，灵活性更高。

两种方案对比 #

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