FastAPI Pydantic模型：设默认值为None并显示Swagger字段描述

要实现字段默认值为None，同时让Swagger显示字段描述，只需给每个字段的Field参数同时指定default=None和description即可，结合可选类型标注确保类型正确。

正确的Pydantic模型写法 #

from typing import Optional
from pydantic import BaseModel, Field

class RegisterRequest(BaseModel):
    user_firstname: Optional[str] = Field(default=None, description="输入你的名字")
    user_lastname: Optional[str] = Field(default=None, description="输入你的姓氏")
    user_dob: Optional[str] = Field(default=None, description="输入你的出生日期（示例格式：YYYY-MM-DD）")
    user_gender: Optional[str] = Field(default=None, description="输入你的性别")
    user_about: Optional[str] = Field(default=None, description="输入关于你的介绍")

如果使用Pydantic v2，可改用更简洁的联合类型标注：

from pydantic import BaseModel, Field

class RegisterRequest(BaseModel):
    user_firstname: str | None = Field(default=None, description="输入你的名字")
    user_lastname: str | None = Field(default=None, description="输入你的姓氏")
    user_dob: str | None = Field(default=None, description="输入你的出生日期（示例格式：YYYY-MM-DD）")
    user_gender: str | None = Field(default=None, description="输入你的性别")
    user_about: str | None = Field(default=None, description="输入关于你的介绍")

关键说明 #

1. 默认值与描述的关联：之前Swagger只显示"string"是因为大部分字段没配置description参数，只要给Field加上该参数，Swagger就会展示对应的描述文本，同时default=None保证用户不传值时字段为None。
2. 关于示例值的误解：你之前用Config.json_schema_extra设置的example只是Swagger界面上的输入示例，不会影响实际请求的默认值——用户不传字段时，后端收到的依然是None，示例值仅作为输入参考，不会被当作实际参数值。

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