如何在FastAPI中设置带建议值的大小写不敏感模型

要同时满足两个需求，你可以结合Literal类型定义和字段验证器：用Literal让SwaggerUI生成建议值，用字段验证器处理大小写转换与合法性校验。

具体实现代码 #

from pydantic import BaseModel, Literal, field_validator
from fastapi import FastAPI

# 定义允许的动作集合，统一维护更方便
ALLOWED_ACTIONS = {"jump", "walk", "sleep"}

class Command(BaseModel):
    # 用Literal定义取值范围，SwaggerUI会据此显示下拉建议
    action: Literal["jump", "walk", "sleep"]

    @field_validator('action')
    @classmethod
    def validate_and_normalize_action(cls, v: str) -> str:
        """将输入转为小写，并验证是否属于允许的动作"""
        lower_action = v.lower()
        if lower_action not in ALLOWED_ACTIONS:
            raise ValueError(f"无效动作，必须是以下之一：{', '.join(ALLOWED_ACTIONS)}")
        return lower_action

app = FastAPI()

@app.post("/execute-command")
async def execute_command(command: Command):
    return {"action": command.action, "status": "executing"}

方案说明 #

1. SwaggerUI建议值展示：通过Literal["jump", "walk", "sleep"]定义字段取值范围，Pydantic会自动生成对应的OpenAPI Schema，SwaggerUI读取后会显示下拉建议列表。
2. 大小写不敏感处理：字段验证器会将用户输入的字符串统一转为小写，再校验是否在允许的动作集合中。无论输入JUMP、Walk还是sleep，都会被转换为合法的小写值；若输入非法值（如run），会触发验证错误，FastAPI自动返回422状态码及错误提示。
3. 可维护性：允许的动作统一存放在常量ALLOWED_ACTIONS中，后续修改或扩展动作时只需改动这一处，无需同时调整Literal和验证器逻辑。

效果验证 #

• 在SwaggerUI（默认路径/docs）中，action字段会显示包含jump、walk、sleep的下拉选项。
• 提交请求时，输入JUMP会被自动转换为jump并正常处理；输入RUN则会返回422错误，提示合法动作列表。

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