How to define a query parameter with multiple values separated by equals signs (=)?

Question

I have an API with this URL:

/api/doSomething?key=value1=value2

Can this be represented in Swagger/OpenAPI 3.0? And if so, how would that look like? Without the second value2 I would specify it like this:

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

Is `?key=value1=value2` the correct format? The commonly used formats are `?key1=value1&key2=value2` and `key=value1,value2`. — Helen, Aug 23 '18 at 13:31
It is the format which is used by the API I'm trying to describe. It looks strange for me too. So I guess there is no way to reflect this with Swagger? — Peter, Aug 23 '18 at 13:57
`=` as a value delimiter is not supported. You'll need to define the parameter as `type: string` and split the value on the server side. As explained here - [Swagger query parameter template](https://stackoverflow.com/q/45485397/113116). — Helen, Aug 23 '18 at 14:12
@Helen If you want you can post your comment as answer as this works for me and I don't think that there is a better solution for this strange API design. — Peter, Aug 24 '18 at 07:38

score 1 · Answer 1 · answered Sep 05 '18 at 15:03

OpenAPI supports the following array value separators in the query string: , | %20. OpenAPI 2.0 also supports \t.

= is NOT supported as a separator for array values.

The most you can do is document your key parameter as type: string and explain the format in the description. Assuming you use openapi: 3.0.0:

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

Also note that = is a reserved character. In OpenAPI 3.0, query parameters have the additional allowReserved attribute that controls whether reserved characters should be sent as-is or percent-encoded.

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

score 0 · Answer 2 · answered Aug 26 '18 at 13:43

The Parameter Object may contain a allowReserved option that allows the use of reserved characters like = in the parameter value. Does the following work for you?

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

How to define a query parameter with multiple values separated by equals signs (=)?

2 Answers2