Question

我使用Swagger-php。当我在查询字符串上定义一个参数时，它可以是一个数组。但从我所看到的情况来看，它并不支持这种查询字符串：

"//div[@id='name']"

我相信如果可能的话，我会设置in the collectionFormatfield。目前我一直在使用https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12，但我想使用上述格式，并让Swagger-UI反映这一点。但是，我读了this github issue，这让我想知道这是否真的有可能并且我错过了它？

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

pipes

这导致以下JSON：

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

Answer 1

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

https://www.typenetwork.com/

Answer 2

现在可以在没有[]最喜欢的答案的情况下执行此操作。使用deepObject样式。

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

这将生成如下所示的网址： q [0] = string1＆q [1] = string2

Answer 3

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

假设您要定义一维数组查询参数（您正在引用涉及多维数组的github问题），这里是当前OpenAPI（fka.Swagger）规范可以提出的内容：

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

您可以在OpenAPI (fka. Swagger) tutorial（披露：我写过）和specification itself (ParameterObject description)

中详细了解这一点

Answer 4

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

我也想知道这个问题已经有一段时间了，但我决定通过js代码，看看我是否可以在那里更改/修复它，我注意到这几行代码：

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 ＆＃39;括号＆＃39; 未在OpenAPI v2 规范中定义。试了一下它似乎在起作用。

Answer 5

请仔细阅读;这对我有用

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

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

'“参数”：[

      {

        "name": "fav",

        "description": "Enter ids of Favoruite",

        "in": "formData",

        "type": "array",

        "items": {

          "type": "integer",

          "format": "int32"

        },

        "paramType": "form",

        "required": true

      }],'

Answer 7

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

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

我对此进行了修改以适合我的用例：

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

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

7 个答案: