Swagger PHP如何描述查询参数中键对应关联数组的场景？

你可以利用OpenAPI的style和explode属性配合Schema定义实现需求，无需逐个编写子参数注解，还能实现代码复用和结构统一。

具体实现步骤 #

第一步：定义公共复用Schema #

先抽离所有from/to结构的通用范围模型，后续所有同类型参数都可以直接引用：

/**
 * @OA\Schema(
 *     schema="RangeFilter",
 *     type="object",
 *     @OA\Property(
 *         property="from",
 *         type="number",
 *         description="区间最小值"
 *     ),
 *     @OA\Property(
 *         property="to",
 *         type="number",
 *         description="区间最大值"
 *     )
 * )
 */

第二步：接口参数处引用Schema #

设置对应的序列化规则，就能自动生成符合要求的参数格式：

/**
 * @OA\Get(
 *     path="/estates",
 *     @OA\Parameter(
 *         name="sqm",
 *         in="query",
 *         description="面积区间过滤",
 *         required=false,
 *         style="deepObject",
 *         explode=true,
 *         @OA\Schema(ref="#/components/schemas/RangeFilter")
 *     ),
 *     @OA\Parameter(
 *         name="test",
 *         in="query",
 *         description="测试区间过滤",
 *         required=false,
 *         style="deepObject",
 *         explode=true,
 *         @OA\Schema(ref="#/components/schemas/RangeFilter")
 *     )
 * )
 */

关键配置说明 #

• style="deepObject"：指定参数按照嵌套对象规则序列化，正好匹配PHP的key[subkey]格式查询参数规则
• explode=true：开启参数展开，生成的接口文档会自动识别子字段，调用时会自动拼接为sqm[from]=xxx&sqm[to]=xxx的格式，服务端接收的$_GET结构和你要求的完全一致

对比你现有写法的优势 #

• 公共Schema只需定义一次，所有同类型区间参数都能直接引用，不用重复编写from/to子参数注解
• 参数结构统一管理，后续要修改区间字段的属性、描述，只需修改Schema定义即可，不用逐个调整参数注解
• 生成的Swagger文档会自动展示嵌套的参数结构，可读性比逐个写子参数的方式更高

内容的提问来源于stack exchange，提问作者shuba.ivan