FastAPI中能否设置带默认值的必填查询参数？

你遇到的问题核心是：FastAPI默认会根据是否设置default自动标记参数的必填状态——设了default就会变成可选，但你需要在OpenAPI文档中标记为必填，同时保留默认值的功能。

有两种实现方式，对应不同的实际需求：

方式一：强制文档标记为必填，允许用户不传（自动用默认值） #

如果你希望用户可以不传递该参数，系统自动使用默认值，但在OpenAPI文档里显示为必填，可以通过openapi_extra手动修改参数的OpenAPI定义：

from fastapi import FastAPI, Query
from enum import Enum

app = FastAPI()

class ModelNames(str, Enum):
    first = "first"
    second = "second"
    third = "third"

@app.post("/path")
async def this_function(
    modelInstance: ModelNames = Query(
        default=ModelNames.first,
        description="a description",
        openapi_extra={"required": True}
    )
):
    return {"selected_model": modelInstance}

这样生成的OpenAPI规范会完全匹配你给出的示例：参数标记为required: true，同时带有default: "first"和枚举选项。

方式二：真正的必填参数（用户必须传递，默认值仅作 fallback） #

如果你希望用户必须显式传递该参数，但如果传递的值不符合要求时使用默认值，可以结合...（表示必填）和函数内的逻辑处理：

@app.post("/path")
async def this_function(
    modelInstance: ModelNames | None = Query(
        ...,
        description="a description"
    )
):
    # 若用户传递无效值，使用默认值（需根据实际场景调整判断逻辑）
    if not modelInstance:
        modelInstance = ModelNames.first
    return {"selected_model": modelInstance}

注意 #

OpenAPI官方规范中，required: true的语义是「客户端必须在请求中包含该参数」，而default仅在参数非必填时生效。如果你严格遵循规范，第一种方式属于「文档层面的标记调整」，第二种才是符合规范的必填+默认值逻辑。

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