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

问题

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"
    }
}

回答1:

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

回答2:

/**
 *     @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
}

回答3:

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)

回答4:

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.

回答5:

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,
 *     )
 */

回答6:

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

      }],'

回答7:

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

来源：https://stackoverflow.com/questions/37878018/can-i-make-swagger-php-use-arrays-on-the-query-string

标签

php

swagger

swagger-ui

swagger-php