How does open api 3.0 support a single query param key with multiple values?

Question

For an api with this format: GET /resource?param=value1&param=value2&param=value3 In open Api 2.0, we can specify like this:

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

But in v3.0 attribute collectionFormat is not available. So while trying with collectionFormat, I received error saying should not have additional property: collectionFormat.

I have searched the documentation but can't find any answer. Does anyone have any idea what should be the new implementation to migrate from 2.0 to 3.0 version?

Ilya Serbis · Accepted Answer · 2023-08-16 15:26:43Z

9

You should use style and explode properties instead:

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

where

explode: true will form param=abc&param=xyz etc and
explode: false will form param=abc,xyz

References:

Detailed description with examples from the Swagger's OpenAPI Guide
Parameter style values with examples in the OpenAPI 3 specification
Corresponding section in the OpenAPI 2 specification (describes the collectionFormat property, which has been replaced in the new version of the specification by the style property)

edited Aug 16, 2023 at 15:26

Ilya Serbis

22.5k8 gold badges92 silver badges78 bronze badges

answered Jun 23, 2020 at 4:36

Ashish Karn

1,1531 gold badge9 silver badges20 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Ashish Karn Over a year ago

explode (true/false) specifies whether arrays and objects should generate separate parameters for each array item or object property. You can check this concept from the schema vs content section of this page.

Simon Logic Over a year ago

why there is no explode=both ? spring mvc supports both types.

Collectives™ on Stack Overflow

How does open api 3.0 support a single query param key with multiple values?

1 Answer 1

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related