FastAPI生成的OpenAPI规范未允许字典值为null，客户端验证失败求方案

问题根源 #

你定义的Value = t.Optional[StrictBool] | t.Optional[StrictInt]在Python层面允许None值，但FastAPI/Pydantic生成OpenAPI schema时，未将null类型纳入additionalProperties的校验规则，导致客户端工具无法识别返回的null值，进而触发验证错误。

方案1：简化类型定义（推荐） #

将Value直接定义为包含None的联合类型，让Pydantic自动生成包含null的合法schema：

# main.py
import typing as t
from pydantic.types import StrictStr
from fastapi import FastAPI
from pydantic import BaseModel, StrictBool, StrictInt, StrictStr

# 直接声明允许布尔、整数或None值
Value = t.Union[StrictBool, StrictInt, None]
# 等价简化写法：Value = t.Optional[StrictBool | StrictInt]

class Example(BaseModel):
    x: dict[StrictStr, Value]

app = FastAPI()

@app.get("/read", response_model=Example)
def read():
    return Example(x={"value": None})

重启服务后，生成的openapi.json中additionalProperties会包含nullable: true（或在anyOf规则中加入{"type": "null"}），客户端工具即可正确识别null值。

方案2：手动扩展Schema（兼容旧版本） #

如果使用较老版本的Pydantic/FastAPI导致方案1不生效，可通过json_schema_extra手动强制添加null类型规则：

import typing as t
from pydantic.types import StrictStr
from fastapi import FastAPI
from pydantic import BaseModel, StrictBool, StrictInt, StrictStr

Value = t.Optional[StrictBool] | t.Optional[StrictInt]

class Example(BaseModel):
    x: dict[StrictStr, Value]

    class Config:
        json_schema_extra = {
            "properties": {
                "x": {
                    "additionalProperties": {
                        "anyOf": [
                            {"type": "boolean"},
                            {"type": "integer"},
                            {"type": "null"}
                        ]
                    }
                }
            }
        }

app = FastAPI()

@app.get("/read", response_model=Example)
def read():
    return Example(x={"value": None})

方案3：精细化字段控制 #

通过Annotated结合Field，单独给字典的额外属性指定可空规则：

import typing as t
from pydantic.types import StrictStr
from fastapi import FastAPI
from pydantic import BaseModel, StrictBool, StrictInt, StrictStr, Field, Annotated

Value = t.Union[StrictBool, StrictInt]

class Example(BaseModel):
    # 给x字段的所有附加属性开启可空支持
    x: Annotated[dict[StrictStr, Value], Field(additionalProperties={"nullable": True})]

app = FastAPI()

@app.get("/read", response_model=Example)
def read():
    return Example(x={"value": None})

内容的提问来源于stack exchange，提问作者dave-edison