Question

我有一个使用以下URL的API：

/api/doSomething?key=value1=value2

这可以在Swagger / OpenAPI 3.0中表示吗？如果是这样，那会是什么样子？如果没有第二个value2，我会这样指定：

  /api/doSomething:
    get:
      summary: ''
      parameters:
      - in: path
        name: key
        description: ''
        required: true
        schema:
          type: string

Answer 1

Parameter Object可能包含一个allowReserved选项，该选项允许在参数值中使用诸如=之类的保留字符。以下内容对您有用吗？

/api/doSomething:
   get:
     summary: ''
     parameters:
     - in: path
       name: key
       description: ''
       required: true
       allowReserved: true
       schema:
         type: string

Answer 2

OpenAPI在查询字符串中支持以下数组值分隔符：, | %20。 OpenAPI 2.0还支持\t。

=不支持作为数组值的分隔符。

您最多只能将key参数记录为type: string，并在description中说明格式。假设您使用openapi: 3.0.0：

parameters:
  - in: query
    name: filter
    required: true
    schema:
      type: string
    description: A list of values separated by `=`.
    example: value1=value2

还要注意，=是reserved character。在OpenAPI 3.0中，查询参数具有附加的allowReserved属性，用于控制保留字符是按原样发送还是按百分比编码发送。

allowReserved: true
/api/doSomething?key=value1=value2
                           ^ 
allowReserved: false
/api/doSomething?key=value1%3Dvalue2
                            ^

如何定义具有多个用等号（=）分隔的值的查询参数？

2 个答案: