Symfony5.4中Swagger UI数组字段生成字符串的配置咨询

问题场景 #

你在Symfony 5.4的API控制器中使用了如下Swagger注解：

* @OA\RequestBody(
 *       @OA\MediaType(
 *           mediaType="multipart/form-data",
 *           @OA\Schema(
 *               @OA\Property(
 *                  property="email",
 *                  type="array",
 *                  @OA\Items(
 *                       type="string"
 *                  ),
 *               )
 *           )
 *       )
 *   )

遇到的问题：

• Swagger UI生成的参数格式为email=test1,test2（CSV格式），而非PHP能识别的email[]=test1&email[]=test2格式
• PHP后端获取到的email是字符串而非数组
• 尝试过collectionFormat=multi，但该参数仅对query或formData类型的参数生效，对multipart/form-data的RequestBody无效

解决方法 #

1. 修改Swagger注解，添加explode=true #

在@OA\Property中添加explode=true配置，强制Swagger UI将数组拆分为多个同名字段提交，同时让PHP正确解析为数组。修改后的注解如下：

* @OA\RequestBody(
 *       @OA\MediaType(
 *           mediaType="multipart/form-data",
 *           @OA\Schema(
 *               @OA\Property(
 *                  property="email",
 *                  type="array",
 *                  explode=true,
 *                  @OA\Items(
 *                       type="string"
 *                  ),
 *               )
 *           )
 *       )
 *   )

2. 控制器中正确获取参数 #

在Symfony控制器里，通过Request对象的request属性或get()方法获取数组参数，确保默认值为空数组：

// 从request属性获取
$emails = $request->request->get('email', []);
// 或者直接用get方法
$emails = $request->get('email', []);

原理说明 #

• OpenAPI对multipart/form-data类型的数组默认采用CSV格式拼接，explode=true会覆盖这一默认行为，将数组元素拆分为多个email[]字段提交，符合PHP对表单数组参数的解析规则。
• collectionFormat=multi仅适用于query参数或传统的formData参数（非RequestBody包裹的multipart类型），因此之前的尝试无法生效。

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