Can I make swagger-php use arrays on the query string?

Question

I use Swagger-php. When I define a parameter that's on the query string it can be an array. But from what I can see, it doesn't support this kind of querystring:

https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12

I believe this would be set in the collectionFormatfield if possible. Currently I've just been using pipes, but I want to use the above format, and have Swagger-UI reflect this, too. However, I read this github issue which has left me wondering if this is actually possible and I've just missed it?

An example of my Swagger-PHP definition:

/**
*     @SWG\Parameter(
*         name="ids",
*         in="query",
*         description="A list of IDs (separated by pipes) to filter the Returns",
*         required=false,
*         type="array",
*         @SWG\Items(
*             type="integer",
*             format="int32"
*         ),
*         collectionFormat="pipes"
*     )
*/

Which results in the following JSON:

"parameters": {
    "ids": {
        "name": "ids",
        "in": "query",
        "description": "A list of IDs (separated by pipes) to filter the Returns",
        "required": false,
        "type": "array",
        "items": {
            "type": "integer",
            "format": "int32"
        },
        "collectionFormat": "pipes"
    }
}

Ima · Accepted Answer · 2018-03-06 07:34:33Z

14

/**
 *     @SWG\Parameter(
 *         name="q[]",
 *         in="query",
 *         description="A list of IDs (separated by new lines) to filter the Returns",
 *         required=false,
 *         type="array",
 *         collectionFormat="multi",
 *         uniqueItems=true,
 *     )
 */

This will result in something similiar to this

{
    "name": "q[]",
    "in": "query",
    "description": "type",
    "required": false,
    "type": "array",
    "collectionFormat": "multi",
    "uniqueItems": true
}

edited Mar 6, 2018 at 7:34

answered Apr 18, 2017 at 7:09

Ima

1,10912 silver badges26 bronze badges

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

2 Comments

George Irimiciuc Over a year ago

This should be the answer. I have spent a few hours searching for answers and as the current answer says, only multi, csv, ssv or tsv are accepted, but adding brackets to the name works with multi. There's no website, blog, or documentation for this case except this comment.

Klaus Over a year ago

Check following for solution without [] hack: stackoverflow.com/a/59034737/2814058

B3none · Accepted Answer · 2019-07-15 09:42:42Z

4

If you haven't already I'd suggest trying the following:

*      @OA\Parameter(
*          name="category[]",
*          description="array of category numbers",
*          in="query",     
*          @OA\Schema( 
*              type="array", 
*              @OA\Items(type="enum", enum={1,2,3,4,5,6,7,8,9}),
*              example={1,2} 
*          )
*      ),

I modified this to fit my use-case:

*    @OA\Parameter(
*      name="things[]",
*      in="query",
*      description="A list of things.",
*      required=false,
*      @OA\Schema(
*        type="array",
*        @OA\Items(type="integer")
*      )
*    ),

Source: https://github.com/zircote/swagger-php/issues/612#issue-380202012

answered Jul 15, 2019 at 9:42

B3none

4094 silver badges18 bronze badges

Comments

Klaus · Accepted Answer · 2019-11-25 15:06:10Z

2

Its now possible to do this without [] hack of most liked answer. Use the deepObject style.

 name: q
 style: deepObject
 schema:
   type: array
   items:
     type: string

This will generate an url like following: q[0]=string1&q[1]=string2

answered Nov 25, 2019 at 15:06

Klaus

1,1911 gold badge11 silver badges16 bronze badges

2 Comments

Helen Over a year ago

deepObject style is not defined for arrays, it's only defined for objects. So this answer is not OpenAPI-compliant. As of March 2021 / OpenAPI 3.1, the correct solution is still to use a parameter named q[], like shown in Ima's answer.

darkbasic Over a year ago

q[] won't generate q[0]=string1&q[1]=string2 but q[]=string1&q[]=string2 so the former is simply not possible yet

Ramesh Adhikari · Accepted Answer · 2018-06-04 12:07:31Z

2

Please go through this; this is work for me

 /**
 *     @SWG\Parameter(
 *         name="id[]",
 *         in="query",
 *         description="A list of IDs (separated by new lines) to filter 
            the Returns",
 *         required=false,
 *         type="array",
 *         collectionFormat="multi",
 *        @SWG\Items(
 *             type="integer",
 *             format="int32"
 *         ),
 *         uniqueItems=true,
 *     )
 */

edited Jun 4, 2018 at 12:07

answered Jun 4, 2018 at 11:28

Ramesh Adhikari

312 bronze badges

Comments

Arnaud Lauret · Accepted Answer · 2016-06-18 16:23:38Z

1

Unfortunately, it is not possible to get exactly the URL you provide (https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12) for an array query parameter.

Assuming that you want to define a 1 dimension array query parameter (the github issue you're refering to concerns multi-dimensional arrays), here's what the current OpenAPI (fka. Swagger) Specification can propose:

If you use an array with a collection format like pipes (you can also use csv, ssv or tsv to get different separators) the URL will look like this:
```
https://api.domain.tld/v1/objects?q=1|5|12
```
But this is not the syntax you're looking for: all array items are defined in a single q query parameter.
Fortunately, there is another collection format multi allowing to define each array's item in its own q parameter, with this one you can almost get what you want minus the []:
```
https://api.domain.tld/v1/objects?q=1&q=5&q=12
```

You can read more about this in this OpenAPI (fka. Swagger) tutorial (disclosure: I wrote it) and in the specification itself (ParameterObject description)

answered Jun 18, 2016 at 16:23

Arnaud Lauret

5,3911 gold badge25 silver badges29 bronze badges

2 Comments

LeonardChallis Over a year ago

Thanks @Arnaud. I considered multi but with PHP you would get just the last value unfortunately, so I've decided to go with pipes after all. Nice tutorial by the way :)

Klaus Over a year ago

Check following how to do it without a hack: stackoverflow.com/a/59034737/2814058

Sophie Su · Accepted Answer · 2024-07-02 17:59:25Z

As of OpenAPI 3.0, the following should work:

/**
 * @OA\Parameter(
 *     name="category[]",
 *     description="array of category numbers",
 *     in="query",     
 *     @OA\Schema( 
 *         type="array", 
 *         @OA\Items(type="enum", enum={1,2,3,4,5,6,7,8,9}),
 *         example={1,2} 
 *     ),
 *     allowedReserved=true
 * ),
 */

allowedReserved prevents [] in name from being encoded into %5B%5D

According to official doc

The default serialization method is style: form and explode: true. This corresponds to collectionFormat: multi from OpenAPI 2.0.

collectionFormat: multi is not required anymore.

You may write it as attribute as well:

new OA\Parameter(
    in: 'query',
    name: 'category[]',
    schema: new OA\Schema(
        type: 'array',
        items: new OA\Items(
            type: 'enum',
            enum: [1,2,3,4,5,6,7,8,9]
        ),
    ),
    description: 'array of category numbers',
    allowReserved: true
),

Jordashiro · Accepted Answer · 2016-10-20 06:42:49Z

0

Disclaimer: im using SwaggerUI, but this might work for you as well.

I was also wondering about this for some time, but i decided to go through the js code and see if i can change/fix it there and i noticed these few lines of code:

if (type === 'brackets' || type === 'multi') {
    var bracket = type === 'brackets' ? '[]' : ''
    for (var i = 0; i < value.length; i++) {
        if (i > 0) {encoded += '&';}

        encoded += this.encodeQueryParam(name) + bracket + '=' + this.encodeQueryParam(value[i]);
    }
}

So it seems there is a collectionFormat 'brackets' that was not defined in the OpenAPI v2 specification. Tried it out and it seems to be working.

answered Oct 20, 2016 at 6:42

Jordashiro

8054 gold badges16 silver badges27 bronze badges

Comments

Muhammad Rashid · Accepted Answer · 2018-12-03 04:00:10Z

0

Following code works fine: See the ScreenShot

'"parameters": [

      {

        "name": "fav",

        "description": "Enter ids of Favoruite",

        "in": "formData",

        "type": "array",

        "items": {

          "type": "integer",

          "format": "int32"

        },

        "paramType": "form",

        "required": true

      }],'

answered Dec 3, 2018 at 4:00

Muhammad Rashid

111 silver badge3 bronze badges

Collectives™ on Stack Overflow

Can I make swagger-php use arrays on the query string?

8 Answers 8

2 Comments

Comments

2 Comments

Comments

2 Comments

Comments

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

8 Answers 8

2 Comments

Comments

2 Comments

Comments

2 Comments

Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related