我能让swagger-php使用查询字符串上的数组吗？

Question

我使用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"
    }
}

- LeonardChallis

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
}

- Ima

---

这应该就是答案。我花了几个小时搜索答案，就像当前的答案所说，只有multi、csv、ssv或tsv被接受，但在名称后面添加括号可与multi一起使用。除了这条评论外，没有任何网站、博客或文档涉及此情况。 - George Irimiciuc

请查看以下解决方案，无需使用[] hack：https://dev59.com/questions/YJjga4cB1Zd3GeqPFh08#59034737 - Klaus

Answer 2

如果您还没有尝试，请尝试以下方法：

*      @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 3.1版本中的错误，该版本未正确处理“@OA\Property”注释标记中的“description”属性。这导致在生成OpenAPI规范文档时描述信息丢失。目前，已经在开发分支上修复了此问题，并将在下一个发布版本中得到解决。

- B3none

Answer 3

请看这个；这是我的工作。

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

- Ramesh Adhikari

Answer 4

现在可以使用deepObject样式来实现此功能，而无需使用最受欢迎答案的[] hack。

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

这将生成类似以下的URL： q[0]=字符串1&q[1]=字符串2

- Klaus

---

数组未定义 deepObject 样式，它仅适用于对象。因此，此答案不符合 OpenAPI 规范。截至 2021 年 3 月 / OpenAPI 3.1，正确的解决方案仍然是使用名为 q[] 的参数，就像 Ima 的答案中所示。 - Helen

Answer 5

很遗憾，无法精确获取您提供的URL（https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12）中的数组查询参数。假设您想定义一个一维数组查询参数（您所参考的GitHub问题涉及多维数组），当前的OpenAPI（前身为Swagger）规范可以提出以下建议：

• 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
  

你可以在这个OpenAPI（原名Swagger）教程中了解更多相关内容（声明：我是作者），以及在规范本身（ParameterObject描述）中了解。

- Arnaud Lauret

---

谢谢@Arnaud。我考虑过multi，但很不幸，在PHP中你只会得到最后一个值，所以我决定终究采用pipes。顺便说一句，很好的教程 :) - LeonardChallis

请查看以下如何在不使用黑客技巧的情况下完成它：https://dev59.com/YJjga4cB1Zd3GeqPFh08#59034737 - Klaus

Answer 6

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

看起来有一个集合格式'brackets'在OpenAPI v2规范中没有定义。尝试了一下，似乎可以工作。

- Jordashiro

Answer 7

以下代码运行良好：查看截图

'"parameters": [

      {

        "name": "fav",

        "description": "Enter ids of Favoruite",

        "in": "formData",

        "type": "array",

        "items": {

          "type": "integer",

          "format": "int32"

        },

        "paramType": "form",

        "required": true

      }],'

- Muhammad Rashid