open api 3.0 如何支持具有多个值的单个查询参数键？

Question

对于这种格式的api：GET /resource?param=value1&param=value2&param=value3 在open Api 2.0中，我们可以这样指定：

parameters:
    - in: query
      name: color
      type: array
      collectionFormat: multi
      items:
        type: string 

但在 v3.0 中，属性 collectionFormat 不可用。因此，在尝试使用 collectionFormat 时，我收到错误消息 should not have additional property: collectionFormat。

我搜索了文档但找不到任何答案。有谁知道从 2.0 版本迁移到 3.0 版本的新实现应该是什么？

Answer 1

您应该使用style和explode属性来代替：

  - name: param
    in: query
    description: Id description
    required: false
    style: form
    explode: true
    schema:
      type: array
      items:
        type: string

在哪里

• explode: true将形成 param=abc¶m=xyz 等
• explode: false将形成 param=abc,xyz

参考：

• Swagger 的 OpenAPI 指南中的详细描述和示例
• OpenAPI 3 规范中的参数样式值和 示例
• OpenAPI 2规范中的对应章节collectionFormat（描述了property，在新版本规范中已被styleproperty取代）