OpenAPI 3如何为字典类型定义可复用的键和值Schema？

这个需求可以实现，只要你定义的#/components/schemas/KEY本身是string类型的Schema（JSON对象的键只能是字符串，这是JSON规范的强制约束，无法突破），具体实现方式如下：

OpenAPI 3.x 版本提供了propertyNames字段用于指定字典键需要符合的Schema约束，additionalProperties字段用于指定字典值的类型，你可以分别给这两个字段配置$ref指向你复用的公共Schema即可。

完整示例：

openapi: 3.0.3
components:
  schemas:
    # 自定义可复用的键约束，必须为string类型Schema
    KEY:
      type: string
      pattern: ^elem\d+$ # 示例规则：键必须符合「elem+数字」的格式
      minLength: 4
    # 自定义可复用的字典值结构
    VALUE:
      type: object
      properties:
        foo:
          type: string
        bar:
          type: integer
    # 包含top字段的根结构定义
    RootStruct:
      type: object
      properties:
        top:
          type: object
          # 指定字典值的类型，引用公共VALUE Schema
          additionalProperties:
            $ref: '#/components/schemas/VALUE'
          # 指定字典键需要符合的规则，引用公共KEY Schema
          propertyNames:
            $ref: '#/components/schemas/KEY'

注意事项 #

• 如果你定义的KEY Schema不是string类型，该需求无法实现，这是JSON本身的语法限制，和OpenAPI无关。
• 如果你使用的是OpenAPI 2.0（Swagger 2.0）版本，不支持propertyNames字段，只能指定字典值的类型，无法对键的规则做复用定义，建议升级到OpenAPI 3.x版本使用该功能。

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