如何手动设置Pydantic模型JSON Schema的description字段（无需修改文档字符串）

不用修改类文档字符串也能实现，下面分Pydantic版本给出具体方法：

Pydantic v1 实现方式 #

方法1：用Config里的schema_extra直接指定 #

通过schema_extra字典注入自定义描述，会覆盖类文档字符串的内容：

from pydantic import BaseModel

class MainModel(BaseModel):
    # 这里不用写类文档字符串，或者保留也会被覆盖
    class Config:
        title = 'Main'
        schema_extra = {
            "description": "这是手动设置的模型描述"
        }

print(MainModel.schema_json(indent=2))

方法2：重载schema方法灵活修改 #

如果需要更复杂的逻辑（比如根据条件动态生成描述），可以直接重载模型的schema类方法：

from pydantic import BaseModel

class MainModel(BaseModel):
    class Config:
        title = 'Main'

    @classmethod
    def schema(cls, **kwargs):
        # 先获取默认生成的schema
        base_schema = super().schema(**kwargs)
        # 替换或添加description字段
        base_schema['description'] = "手动设置的模型描述"
        return base_schema

print(MainModel.schema_json(indent=2))

Pydantic v2 实现方式 #

v2推荐使用model_config配置，以下两种方法都可行：

方法1：通过model_config的schema_extra设置 #

from pydantic import BaseModel, ConfigDict

class MainModel(BaseModel):
    model_config = ConfigDict(
        title='Main',
        schema_extra={
            "description": "这是手动设置的模型描述"
        }
    )

# v2用model_json_schema()获取schema
print(MainModel.model_json_schema())

方法2：使用__pydantic_modify_schema__钩子 #

这个钩子专门用于自定义修改生成的schema，适合需要动态调整的场景：

from pydantic import BaseModel

class MainModel(BaseModel):
    model_config = ConfigDict(title='Main')

    @classmethod
    def __pydantic_modify_schema__(cls, schema: dict[str, object]) -> None:
        schema['description'] = "手动设置的模型描述"

print(MainModel.model_json_schema())

为什么直接在Config里加description无效？因为Pydantic的配置类（v1）或ConfigDict（v2）并没有内置description参数，title是官方明确支持的配置项，但description默认绑定类的文档字符串，所以需要用上述方法手动覆盖。

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