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
– Helen, Commented Aug 23, 2018 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
– Peter, Commented Aug 23, 2018 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. — Helen
– Helen, Commented Aug 23, 2018 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
– Peter, Commented Aug 24, 2018 at 7:38

Helen · Accepted Answer · 2018-09-05 15:03:56Z

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
                            ^

Patrick Atoon · Accepted Answer · 2018-08-26 13:43:31Z

0

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

answered Aug 26, 2018 at 13:43

Patrick Atoon

7698 silver badges9 bronze badges

Collectives™ on Stack Overflow

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

2 Answers 2

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related