使用zircote/swagger-php 2.x提交对象数组参数的方案问询

你遇到的问题是Swagger 2.0规范本身的限制：当参数位置是in="query"时，直接用type="array"搭配@SWG\Items(type="object")是不被允许的——Query参数的数组元素只能是简单类型（字符串、数字、布尔值等），不能直接定义为对象。不过不用转成JSON字符串数组，有更合规的解决方案：

改用@SWG\Schema包裹数组对象结构 #

在@SWG\Parameter内部，不要直接设置type="array"，而是用@SWG\Schema来定义完整的数组+对象结构，这样swagger-php就能正确识别了。示例代码如下：

/**
 * @SWG\Parameter(
 *     name="foo",
 *     in="query",
 *     required=true,
 *     @SWG\Schema(
 *         type="array",
 *         @SWG\Items(
 *             type="object",
 *             @SWG\Property(property="id", type="string"),
 *             @SWG\Property(property="position", type="string")
 *         )
 *     )
 * )
 */

关于参数传递格式 #

这种定义对应的前端传递格式应该是嵌套键值对，比如：

foo[0][id]=abc123&foo[0][position]=top&foo[1][id]=def456&foo[1][position]=bottom

大部分后端框架（比如Laravel、Symfony）都能自动解析这种格式为对象数组。

为什么原来的写法不行？ #

zircote/swagger-php ^2.0严格遵循Swagger 2.0规范：Query参数的type="array"仅支持元素为简单类型的数组，而对象数组的结构需要通过schema属性来定义，这样才能绕过简单类型的限制，同时符合规范要求。

内容的提问来源于stack exchange，提问作者fabpico