FastAPI中如何让Swagger UI展示可选字符串字段的默认null值

嗨，这个问题我之前也碰到过！其实根源在于OpenAPI规范默认会给字符串类型生成"string"作为示例值，哪怕你的字段是Optional且默认None。不过有几个简单的办法可以让Swagger UI里的示例直接显示null，不用让用户手动修改：

方法一：给每个Field添加example参数 #

最直接的方式就是在定义Field的时候，明确指定example=None，这样Swagger UI就会把这个示例值展示出来，替代默认的"string"。修改后的模型代码如下：

from pydantic import BaseModel, Field, Optional

class MyModel(BaseModel):
    comment: Optional[str] = Field(None, description='Comment', example=None)
    description: Optional[str] = Field(None, description='Description', example=None)

这样调整后，你再打开Swagger UI的请求示例，就能看到"comment": null和"description": null了，用户直接用这个示例提交的话，字段值就是None，完全符合你的需求。

方法二：给模型添加全局示例配置 #

如果你的模型里有很多可选字段，一个个加example参数太麻烦，也可以通过Pydantic的模型配置来设置全局的示例。只需要在模型里添加Config类，用schema_extra定义整个模型的示例结构：

from pydantic import BaseModel, Field, Optional

class MyModel(BaseModel):
    comment: Optional[str] = Field(None, description='Comment')
    description: Optional[str] = Field(None, description='Description')

    class Config:
        schema_extra = {
            "example": {
                "comment": None,
                "description": None
            }
        }

这种方式会给整个模型设置一个完整的示例，Swagger UI会直接展示这个自定义的示例，同样能达到让可选字段显示null的效果。

这两种方法都不需要你在接口里额外处理"string"转None的逻辑，直接从Swagger示例层面解决问题，用户体验会更好。

备注：内容来源于stack exchange，提问作者Marharyta Varatnitskaya