如何导出含所有枚举值的Pydantic ModelX为指定JSON格式？

核心思路 #

默认情况下，Pydantic生成的JSON Schema会将枚举定义为$ref引用形式，我们需要修改Schema生成逻辑，把枚举的所有成员值直接嵌入到对应字段的Schema中，而非引用。

实现步骤 #

1. 定义基础枚举与模型 #

先看示例枚举和ModelX的基础写法：

from enum import Enum
from pydantic import BaseModel
from pydantic.json_schema import schema_json_of

class StatusEnum(str, Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"
    PENDING = "pending"

class ModelX(BaseModel):
    status: StatusEnum
    name: str

直接调用schema_json_of(ModelX)时，输出的Schema里status字段会引用#/$defs/StatusEnum，无法直接看到枚举值。

2. 自定义JSON Schema生成器 #

通过继承GenerateJsonSchema重写枚举的Schema生成逻辑，实现枚举值展开：

from pydantic import ConfigDict
from pydantic.json_schema import GenerateJsonSchema

class EnumExpandingGenerateJsonSchema(GenerateJsonSchema):
    def enum_schema(self, enum_type: type[Enum]) -> dict:
        schema = super().enum_schema(enum_type)
        # 移除引用标识，直接保留枚举值列表
        schema.pop('$ref', None)
        # 注入所有枚举成员值
        schema['enum'] = [member.value for member in enum_type]
        # 可选：添加描述说明
        schema['description'] = f"可选值：{', '.join(schema['enum'])}"
        return schema

# 给模型配置自定义生成器
model_config = ConfigDict(
    json_schema_generate=EnumExpandingGenerateJsonSchema()
)

class ModelX(BaseModel):
    model_config = model_config
    status: StatusEnum
    name: str

3. 生成展开后的JSON Schema #

此时调用schema_json_of(ModelX)，输出的JSON中status字段会直接包含所有枚举值：

{
  "type": "object",
  "properties": {
    "status": {
      "enum": ["active", "inactive", "pending"],
      "type": "string",
      "description": "可选值：active, inactive, pending"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["status", "name"]
}

4. 直接输出枚举值供API响应使用 #

如果不需要完整JSON Schema，仅需枚举值列表用于UI展示或预验证，可直接提取枚举成员：

# 生成枚举值列表
status_values = [member.value for member in StatusEnum]
# 生成带键值对的字典（可选）
status_options = {member.name: member.value for member in StatusEnum}

# 示例：在FastAPI接口中返回
# @app.get("/status-options")
# async def get_status_options():
#     return {"available_status": status_values}

注意事项 #

• 若使用Pydantic v1版本，需通过schema_extra或自定义Field的schema参数实现枚举展开
• 确保枚举继承自str/int等可序列化类型，避免序列化异常

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