Pydantic v2升级后可选字段OpenAPI规范与响应验证问题

问题拆解 #

• Pydantic v2中Optional[str] = None会生成anyOf string/null的OpenAPI Schema，且被标记为必填，导致下游代码生成工具异常
• 改为str = None后，OpenAPI Schema恢复正常，但SqlAlchemy返回的None会被判定为已设置的无效值，触发ResponseValidationError，response_model_exclude_none=True无法解决此问题

可行解决方案 #

1. 字段定义调整 #

将模型字段改为以下形式：

from pydantic import BaseModel, Field

class ExampleModel(BaseModel):
    color: str = Field(default=None, nullable=False)

• default=None：告知Pydantic字段有默认值，OpenAPI会标记为非必填
• nullable=False：强制Schema类型为string，避免生成anyOf结构

2. 全局启用排除空值配置 #

在FastAPI应用全局开启，无需逐个端点设置：

from fastapi import FastAPI

app = FastAPI(response_model_exclude_none=True)

或者在模型中添加全局配置：

class ExampleModel(BaseModel):
    color: str = Field(default=None, nullable=False)
    
    class Config:
        exclude_none = True

3. 批量修改技巧 #

针对100个端点的批量处理：

• 用正则表达式批量替换代码中的Optional\[str\] = None为str = Field(default=None, nullable=False)
• 统一全局配置response_model_exclude_none=True，减少重复操作

原理说明 #

Field(default=None, nullable=False)既满足OpenAPI Schema的要求（显示为string类型、非必填），又通过默认值的方式允许运行时字段为None；全局exclude_none配置会在序列化响应时自动移除None值字段，避免SqlAlchemy返回的空值触发验证错误。

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