OpenAPI 3的oneOf用法在OpenAPI 2.0中的等价实现及代码适配

OpenAPI 2.0（即 Swagger 2.0）原生不支持 oneOf 关键字，我们可以通过多类型声明的方式实现等效效果，转换后的代码如下：

formats:
  type: array
  description: 允许的参数格式
  items:
    type: [string, object]
    description: |
      取值可以是字符串格式，或者匹配的别名格式对象
      当类型为 object 时字段定义如下：
    properties:
      representation:
        type: array
        description: 别名格式表示列表
        items:
          type: string
      match_multiple:
        type: boolean
        description: 可选字段，是否匹配多个
      display:
        type: string
        description: 别名格式的展示文本
    required:
      - representation
      - display

转换说明 #

• 移除了 oneOf 声明，改用 type: [string, object] 直接声明数组项支持的两种类型
• 原对象的属性定义直接放在 items 层级下，校验时会自动匹配对应类型的结构：如果是字符串则不会校验属性，如果是对象则会校验对应属性是否符合要求
• 原代码中 optional: true 的写法改为 Swagger 2.0 标准规则：通过 required 数组指定必填字段，不在数组内的 match_multiple 默认为可选字段

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