我可以让 swagger-php 在查询字符串上使用数组吗？

Question

我使用 Swagger-php。当我在查询字符串上定义一个参数时，它可以是一个数组。但据我所知，它不支持这种查询字符串：

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

我相信这会被设置 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 这让我想知道这是否真的可行，我只是错过了它？

我的 Swagger-PHP 定义的一个例子：

/**
*     @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"
*     )
*/

结果如下 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"
    }
}

Answer 1

不幸的是，无法完全您为数组查询参数提供的URL (https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12)。

假设您想要定义一维数组查询参数（您所指的 github 问题涉及多维数组），这是当前 OpenAPI (fka.Swagger) 规范可以提出的建议:

如果你使用集合格式如pipes的数组（你也可以使用csv、ssv或tsv得到不同的分隔符） URL 将如下所示：
```
https://api.domain.tld/v1/objects?q=1|5|12
```
但这不是您要查找的语法：所有数组项都在单个 q 查询参数中定义。
幸运的是，还有另一种集合格式 multi 允许在其自己的 q 参数中定义每个数组的项目，使用这个你可以 almost 得到你想要的减去 []:
```
https://api.domain.tld/v1/objects?q=1&q=5&q=12
```

您可以在 OpenAPI (fka. Swagger) tutorial (disclosure: I wrote it) and in the specification itself (ParameterObject description)

中阅读更多相关信息

Answer 2

免责声明：我正在使用 SwaggerUI，但这可能也适用于您。

我也想知道这个有一段时间了，但我决定查看 js 代码，看看我是否可以 change/fix 它在那里，我注意到以下几行代码：

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]);
    }
}

所以似乎有一个 collectionFormat 'brackets' 未在 OpenAPI v2 规范中定义。试了一下，好像还行。

Answer 3

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

这将导致类似于此的结果

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

Answer 4

请完成这个；这对我有用

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

Answer 5

以下代码工作正常：See the ScreenShot

'"parameters": [

      {

        "name": "fav",

        "description": "Enter ids of Favoruite",

        "in": "formData",

        "type": "array",

        "items": {

          "type": "integer",

          "format": "int32"

        },

        "paramType": "form",

        "required": true

      }],'

Answer 6

如果您还没有，我建议您尝试以下方法：

*      @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} 
*          )
*      ),

我修改了它以适合我的 use-case:

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

来源：https://github.com/zircote/swagger-php/issues/612#issue-380202012

Answer 7

现在无需 [] 黑客最喜欢的答案就可以做到这一点。使用 deepObject 样式。

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

这将生成如下所示的 url： q[0]=string1&q[1]=string2

我可以让 swagger-php 在查询字符串上使用数组吗？

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

php

swagger

swagger-php

swagger-ui