如何为SQLModel的Field()添加示例？Pydantic可行但SQLModel报错

SQLModel基于Pydantic v2实现，而Pydantic v2已弃用单数的example参数，改用符合OpenAPI 3规范的写法，所以直接用example会报错。以下是几种可行的实现方式：

1. 使用examples参数（推荐） #

SQLModel的Field支持复数形式的examples参数，传入列表格式的示例值，会直接在Swagger文档中展示：

from sqlmodel import SQLModel, Field

class Item(SQLModel):
    name: str = Field(default=None, examples=["A very nice Item"])
    price: float = Field(default=None, examples=[9.99])

2. 使用json_schema_extra参数 #

如果需要更自定义的示例格式，可以通过json_schema_extra传入包含example的字典：

from sqlmodel import SQLModel, Field

class Item(SQLModel):
    name: str = Field(default=None, json_schema_extra={"example": "A very nice Item"})
    price: float = Field(default=None, json_schema_extra={"example": 9.99})

3. 模型级统一设置示例 #

如果要给整个模型添加完整的示例，可以在模型的Config类中定义schema_extra：

from sqlmodel import SQLModel

class Item(SQLModel):
    name: str
    price: float

    class Config:
        schema_extra = {
            "example": {
                "name": "A very nice Item",
                "price": 9.99
            }
        }

补充说明 #

SQLModel不支持example参数的核心原因是对齐了Pydantic v2和OpenAPI 3的规范，单数example属于旧版OpenAPI 2的用法，现在官方推荐用复数examples或json_schema_extra来定义示例内容。

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