Swagger UI：post 请求正文中的对象数组忽略了 explode=true

Question

我正在尝试使用 Swagger 来记录具有对象数组参数的 API POST 调用。但是当我尝试在 Swagger UI 中测试它时，explode: true 似乎在 encoding:filters 中被忽略了。这是我的代码：

openapi: 3.0.2
info:
  description: >-
    My API
  version: 1.0.0
  title: My API
tags:
  - name: myApi
    description: my API
paths:
  /myApi/getList:
    post:
      tags:
        - myApi
      summary: gets a list
      description: gets a list
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                sourceId:
                  type: integer
                  description: the source id
               filters:
                  type: array
                  items:
                    $ref: '#/components/schemas/Filter'
            encoding:
              filters:
                contentType: application/json
                explode: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '500':
          description: error
components:
  schemas:
    Filter: 
      type: object
      properties:
        field:
          type: string
          description: the name of the field for this filter
        selection:
          type: array
          items:
            type: string
            description: the name of a selected value of the filter field
      required: [attribUniqueName, selection]

如果我用e作为参数。 g.

sourceId: 1

filters: [
  {
    "field": "product",
    "selection": ["Prod A", "Prod B"]
  },
  {
    "field": "country",
    "selection": ["USA", "France"]
  }
]

然后 Swagger UI 使用（如果我省略 URL 编码以获得更好的可读性）生成调用：

sourceId=1&filters={"field":"product","selection":["Prod A","Prod B"]},{"field":"country","selection":["USA","France"]}

我怎样才能让它产生

sourceId=1&filters={"field":"product","selection":["Prod A","Prod B"]}&filters={"field":"country","selection":["USA","France"]}

代替？

OpenAPI 3.0.2 documentation for "Encoding Object"表示explode属性"SHALL be ignored if the request body media type is not application/x-www-form-urlencoded."但是我们这里用的是application/x-www-form-urlencoded。还是文档有误，它应该声明 "the content type the current object" 而不是 "the request body media type"？但是，我会假设得到一个真正的数组作为参数值，i。 e.

sourceId=1&filters=[{"field":"product","selection":["Prod A","Prod B"]},{"field":"country","selection":["USA","France"]}]

如果重要：我正在使用 Swagger UI 版本 3.24.3。

Answer 1

你的代码看起来不错，实际问题是encoding is not yet supported by Swagger UI.

有关 Github 的相关问题，请参阅 here。它有一个字符串数组的示例，而不是像您的情况那样的对象数组，但可能只要它不适用于字符串，它也不适用于对象。

Swagger UI：post 请求正文中的对象数组忽略了 explode=true

Swagger UI: explode=true ignored for object array in post request body

swagger

swagger-ui

swagger-3.0