FastAPI文档下拉框显示完整文本，值保留短标识的实现方法

我定义了如下用于字段校验的Gender枚举类：

class Gender(str, Enum):
    male = "m"
    female = "f"

在FastAPI自动生成的文档页面中，该枚举对应的下拉选择框的选项文本显示为m和f，生成的HTML代码如下：

<select class=""><option value="">--</option><option value="m">m</option><option value="f">f</option></select>

我希望下拉框的选项文本显示为Male和Female，但对应的值仍保留m和f，即生成的Swagger HTML如下：

<select class=""><option value="">--</option><option value="m">Male</option><option value="f">Female</option></select>

请问该如何实现？

你可以通过给枚举类的每个成员添加文档字符串（__doc__）来实现需求，FastAPI的Swagger UI会读取这些文档字符串作为下拉选项的显示文本，同时保留枚举成员的原始值。

方式一：直接给成员添加文档字符串 #

修改后的枚举类代码如下：

from enum import Enum

class Gender(str, Enum):
    male = "m"
    male.__doc__ = "Male"
    
    female = "f"
    female.__doc__ = "Female"

方式二：重写枚举__new__方法统一处理 #

如果枚举成员较多，这种方式更优雅：

from enum import Enum

class Gender(str, Enum):
    male = "m"
    female = "f"

    def __new__(cls, value):
        # 创建枚举成员实例
        member = str.__new__(cls, value)
        member._value_ = value
        
        # 映射值与友好显示名称
        display_names = {
            "m": "Male",
            "f": "Female"
        }
        member.__doc__ = display_names.get(value, value)
        return member

修改后，FastAPI生成的OpenAPI规范会包含每个枚举成员的描述信息，Swagger UI就会将Male和Female作为下拉框的选项文本展示，实际提交的值仍然是m和f，完全符合需求。

内容的提问来源于stack exchange，提问作者Md Abdur Rakib