如何在OpenAPI spec中定义键为Enum的Map<Enum,String>类型参数？

在OpenAPI规范里，完全可以将Map类型参数的键定义为枚举类型，并非只能用字符串类型，具体实现分版本来看：

• OpenAPI 3.x（推荐）
  用propertyNames关键字配合enum约束对象的键，同时用additionalProperties定义值的类型，完美实现Map<Enum, String>的结构：

  components:
    schemas:
      EnumKeyedStringMap:
        type: object
        # 约束键必须是指定的枚举值
        propertyNames:
          enum: ["USER_ROLE", "USER_STATUS", "USER_TYPE"]
        # 定义值为字符串类型
        additionalProperties:
          type: string
  

  这种写法能让API校验工具、代码生成器识别出键的枚举约束，生成对应语言的枚举类型作为Map的键。

• OpenAPI 2.0（Swagger 2.0）
  该版本没有propertyNames关键字，只能退而求其次：把键声明为字符串类型，在描述里说明它只能取枚举值，或者用pattern正则匹配枚举的字符串形式。比如：

  definitions:
    EnumKeyedStringMap:
      type: object
      additionalProperties:
        type: string
      description: 键只能是USER_ROLE、USER_STATUS、USER_TYPE中的一个
  

  这种方式没有强校验能力，仅靠文档说明，不如3.x版本严谨。

需要注意：无论哪种写法，实际HTTP传输或JSON序列化时，键本质还是字符串形式，OpenAPI的枚举约束是校验这些字符串必须属于指定的枚举集合，逻辑上等价于把键设为枚举类型。

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