如何在OpenAPI文档中同时展示枚举的键与对应值？

默认情况下，Pydantic对IntFlag类型的OpenAPI schema生成仅展示枚举数值，若要同时显示枚举键与对应数值，可通过以下几种方式实现：

方法一：给字段添加手动描述（最简单） #

直接在模型的code字段上用Field添加包含键值对的描述，无需修改枚举类：

from enum import IntFlag
from pydantic import BaseModel, Field

class ResponseCode(IntFlag):
    request_failed = 1000
    request_success = 1001

class Response(BaseModel):
    success: bool
    message: str
    code: ResponseCode = Field(
        description="枚举选项：\n" + "\n".join([f"- {item.name}: {item.value}" for item in ResponseCode])
    )

生成的OpenAPI文档中，code字段的描述会列出所有枚举键和对应数值，清晰展示对应关系。

方法二：自定义枚举的JSON Schema生成（自动全局生效） #

如果希望所有使用该枚举的字段都自动带上键值描述，可以重写枚举类的__get_pydantic_json_schema__方法：

from enum import IntFlag
from pydantic import BaseModel
from pydantic_core import core_schema

class ResponseCode(IntFlag):
    request_failed = 1000
    request_success = 1001

    @classmethod
    def __get_pydantic_json_schema__(cls, core_schema, handler):
        # 先获取默认的schema
        schema = handler(core_schema)
        # 添加包含键值对的描述
        schema['description'] = "枚举选项：\n" + "\n".join([f"- {item.name}: {item.value}" for item in cls])
        return schema

class Response(BaseModel):
    success: bool
    message: str
    code: ResponseCode

这种方式会让所有引用ResponseCode的字段，在OpenAPI文档中自动带上键值说明，无需重复配置。

方法三：改用IntEnum并序列化键值对（若无需位运算） #

如果不需要IntFlag的位运算功能，改用IntEnum并添加序列化器，可让接口返回和OpenAPI文档同时展示键值信息：

from enum import IntEnum
from pydantic import BaseModel, field_serializer
from pydantic_core import core_schema

class ResponseCode(IntEnum):
    request_failed = 1000
    request_success = 1001

    @classmethod
    def __get_pydantic_json_schema__(cls, core_schema, handler):
        schema = handler(core_schema)
        schema['description'] = "\n".join([f"- {item.name}: {item.value}" for item in cls])
        return schema

class Response(BaseModel):
    success: bool
    message: str
    code: ResponseCode

    @field_serializer('code')
    def serialize_code(self, code: ResponseCode):
        return {"name": code.name, "value": code.value}

此时接口返回的code字段会是包含键和值的对象，同时OpenAPI文档也会展示对应的键值说明。

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