如何用Swagger 2.0描述多类型参数？OpenAPI3.0 YAML转译求助

Swagger 2.0 不支持 oneOf 关键字，需要针对你的两个参数做如下适配性调整：

1. ip 查询参数转译 #

原 OpenAPI 3.0 用 oneOf 指定参数为 IPv4 或 IPv6 格式，Swagger 2.0 可通过「字符串类型+格式描述+正则校验」实现等价效果：

- name: ip
  in: query
  type: string
  description: 支持 IPv4 或 IPv6 格式的地址
  pattern: '^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$|^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$'

若不需要严格正则校验，可简化为只保留类型和格式说明：

- name: ip
  in: query
  type: string
  description: 输入值需为 IPv4 或 IPv6 格式的地址

2. ipv4 参数转译 #

原 OpenAPI 3.0 用 oneOf 指定参数为单个 Ipv4Type 实例或 Ipv4 数组，Swagger 2.0 不支持分支类型定义，可选择以下两种方案：

方案一：用扩展字段模拟 oneOf（部分工具兼容） #

- name: ipv4
  in: query  # 补充原代码缺失的参数位置，若为其他位置可替换为 path/body 等
  x-oneOf:
    - $ref: 'xxx/Ipv4Type'
    - type: array
      items:
        $ref: 'xxx/Ipv4'
  description: 支持单个 IPv4 类型实例或 IPv4 地址数组

方案二：标准 Swagger 2.0 写法（兼容性最优） #

通过描述明确参数允许的两种类型，并拆分结构定义：

- name: ipv4
  in: query
  description: 可传入单个 IPv4 类型实例，或 IPv4 地址组成的数组
  schema:
    type: object
    properties:
      singleIpv4:
        $ref: 'xxx/Ipv4Type'
      ipv4Array:
        type: array
        items:
          $ref: 'xxx/Ipv4'
    description: 二选一传入 singleIpv4 或 ipv4Array

如果该参数是请求体参数，可调整为带类型标识的结构：

- name: ipv4
  in: body
  description: 支持单个 IPv4 类型实例或 IPv4 地址数组
  schema:
    type: object
    properties:
      type:
        type: string
        enum: ['single', 'array']
      singleValue:
        $ref: 'xxx/Ipv4Type'
      arrayValue:
        type: array
        items:
          $ref: 'xxx/Ipv4'
    required: [type]

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