FastAPI中如何让Swagger UI为可选字段显示null而非string/0.0占位值？

我之前也碰到过这个糟心的问题！Swagger默认的示例值确实很容易误导用户，不小心就会把"string"或者0.0这种占位符传到后端，最后存进数据库搞出脏数据。下面给你几个实用的解决办法：

一、字段级精准定制示例 #

你之前只加了example=None没生效？那是因为还要结合OpenAPI的Schema配置，明确告诉Swagger这个字段可以为null，并且示例就是null。直接在Field里补充配置就行：

from typing import Optional
from pydantic import BaseModel, Field

class MyModel(BaseModel):
    factory_id: Optional[str] = Field(
        default=None,
        example=None,
        json_schema_extra={"nullable": True}
    )
    price: Optional[float] = Field(
        default=None,
        example=None,
        json_schema_extra={"nullable": True}
    )

如果是用Pydantic v2的话，nullable参数已经被整合到类型注解里了（Optional本身就表示可空），但还是可以通过json_schema_extra强制指定示例和可空属性，确保Swagger能正确识别。

另外，你也可以给整个模型设置统一的示例模板，这样Swagger会直接用你定义的示例：

class MyModel(BaseModel):
    factory_id: Optional[str] = Field(default=None)
    price: Optional[float] = Field(default=None)

    class Config:
        json_schema_extra = {
            "examples": {
                "default": {
                    "summary": "标准请求示例",
                    "value": {
                        "factory_id": None,
                        "price": None
                    }
                }
            }
        }

这样Swagger里就会直接展示你定义的带null的示例，不会再用默认的占位符了。

二、全局统一修改Swagger示例规则 #

如果你的项目里有大量可选字段，一个个改太麻烦，可以全局配置OpenAPI生成逻辑，自动把所有可选字段的示例改成null：

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI(title="你的项目名称", version="1.0")

def custom_openapi():
    # 避免重复生成schema
    if app.openapi_schema:
        return app.openapi_schema
    # 生成基础的OpenAPI schema
    openapi_schema = get_openapi(
        title=app.title,
        version=app.version,
        description=app.description,
        routes=app.routes,
    )
    # 遍历所有模型schema，修改可选字段的示例
    for schema in openapi_schema["components"]["schemas"].values():
        if "properties" not in schema:
            continue
        for prop in schema["properties"].values():
            # 判断字段是否可空（包含null类型）
            if "null" in prop.get("type", []) or prop.get("nullable", False):
                prop["example"] = None
    # 缓存生成好的schema
    app.openapi_schema = openapi_schema
    return openapi_schema

# 替换默认的openapi生成函数
app.openapi = custom_openapi

这样不管你新增多少个可选字段，Swagger都会自动显示null作为示例，一劳永逸。

三、兜底验证：拒绝占位符数据 #

如果怕还是有用户手动输入string或0.0，还可以给字段加验证规则，直接拒绝这些明显的占位符值：

from pydantic import BaseModel, Field, validator
from typing import Optional

class MyModel(BaseModel):
    factory_id: Optional[str] = Field(default=None)
    price: Optional[float] = Field(default=None)

    @validator("factory_id")
    def reject_default_string(cls, value):
        if value == "string":
            raise ValueError("请输入有效的工厂ID，不能使用默认占位符'string'")
        return value

    @validator("price")
    def reject_default_float(cls, value):
        # 注意：如果你的业务允许合法的0.0值，就不要加这个验证！
        if value == 0.0 and value is not None:
            raise ValueError("请输入有效的价格，不能使用默认占位符0.0")
        return value

不过这个方法要谨慎用——如果你的业务场景里用户确实需要输入0.0，这个验证就会误判合法请求，所以只适合绝对不允许这些占位符的场景。

总的来说，优先用前两种方法修改Swagger的示例展示，从源头避免用户误操作；如果有特殊需求，再加上验证兜底就万无一失了。

内容来源于stack exchange