如何在OpenAPI YAML中定义含可选动态键的响应Schema

你现有Schema的问题在于结构设计和目标响应不匹配：一是固定要求metricType、metrics为必填字段，二是多余的嵌套层级不符合外层直接放可选键的需求，调整方式如下。

适配固定两个可选键的场景 #

如果确定只会返回fieldProfile、summaryProfile这两个键，直接把两个键定义为根对象的可选属性即可，不需要metricType相关嵌套结构：

ProfileMetrics:
  description: 指标配置响应结构
  type: object
  properties:
    fieldProfile:
      type: array
      description: 配置文件类型指标列表
      items:
        type: string
    summaryProfile:
      type: array
      description: 摘要配置指标列表
      items:
        type: string
  # 不配置required规则，两个属性默认均为可选
  # 天然支持仅返回单个字段、同时返回两个字段的场景
  additionalProperties: false # 可选配置，禁止返回未定义的额外字段

如果你实际接口返回的数组项不是纯字符串，而是带metricName字段的对象，只需要把items下的配置替换成你原来写的对象结构即可，外层可选键的逻辑不受影响。

适配动态扩展metricType的场景 #

如果后续需要支持更多同类型的指标键（比如后续新增xxxProfile类型的键），不需要逐个硬编码属性，可以用正则匹配动态键：

ProfileMetrics:
  description: 指标配置响应结构（支持动态指标类型键）
  type: object
  patternProperties:
    # 正则匹配所有以Profile结尾的合法键名
    "^(field|summary|[a-zA-Z]+)Profile$":
      type: array
      items:
        type: string
  additionalProperties: false

这个配置会自动识别所有符合命名规则的指标类型键，新增类型时不需要修改Schema。

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