FastAPI：如何让IntEnum在openapi.json生成带键的可读枚举模式？

场景说明 #

我定义了如下Python IntEnum类：

from enum import IntEnum

class Role(IntEnum):
    client = 1
    manager = 2
    admin = 3

当前生成的openapi.json中该枚举的输出为：

{
  "enum": [1, 2, 3],
  "title": "Role",
  "type": "integer"
}

我需要生成的自定义格式为：

{
  "enum": {
    "client": 1,
    "manager": 2,
    "admin": 3
  },
  "title": "Role",
  "type": "integer"
}

可行方案 #

可以实现，但要明确：OpenAPI官方规范中enum字段的标准类型是数组，这种对象格式属于自定义扩展，可能不兼容部分OpenAPI生态工具（如Swagger UI、Redoc）。

具体实现方式分工具场景：

• 若使用FastAPI/Starlette：编写自定义OpenAPI生成钩子，遍历生成的Schema结构，定位到Role对应的Schema节点，将原有enum数组替换为枚举成员名与值的键值对对象。
• 若使用其他OpenAPI生成库：扩展库的枚举序列化逻辑，重写枚举的输出方法，把枚举的成员映射转换为对象格式输出。

如果仅用于内部特定场景，无需兼容通用OpenAPI工具，这个修改完全可行。

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