5

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

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

如果可能的话，我相信这将在collectionFormat现场设置。目前我一直在使用pipes，但我想使用上述格式，并让 Swagger-UI 也反映这一点。但是，我阅读了这个 github 问题，这让我想知道这是否真的可行，而我只是错过了它？

我的 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"
    }
}
4

7 回答 7

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

生成的图像

于 2017-04-18T07:09:40.400 回答
2

请通过这个；这对我有用

 /**
 *     @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,
 *     )
 */
于 2018-06-04T11:28:43.653 回答
2

现在可以在没有 [] hack 最喜欢的答案的情况下做到这一点。使用 deepObject 样式。

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

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

于 2019-11-25T15:06:10.583 回答
1

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

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

  • 如果您使用具有集合格式的数组pipes（您也可以使用csv,ssv或tsv获取不同的分隔符），则 URL 将如下所示： 

    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) 教程（披露：我写的）和规范本身（ParameterObject 描述）中阅读更多相关信息

于 2016-06-18T16:23:38.980 回答
1

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

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

于 2019-07-15T09:42:42.340 回答
0

免责声明：我正在使用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]);
    }
}

因此，OpenAPI v2规范中似乎没有定义一个collectionFormat 'brackets' 。试了一下，它似乎工作。

于 2016-10-20T06:42:49.000 回答
0

以下代码工作正常：请参阅屏幕截图

'“参数”： [

      {

        "name": "fav",

        "description": "Enter ids of Favoruite",

        "in": "formData",

        "type": "array",

        "items": {

          "type": "integer",

          "format": "int32"

        },

        "paramType": "form",

        "required": true

      }],'
于 2018-12-03T04:00:10.747 回答