如何在 Swagger UI 中正确声明字符串数组以避免逗号分隔的字符串问题-php教程-PHP中文网

如何在 Swagger UI 中正确声明字符串数组以避免逗号分隔的字符串问题

Swagger UI 默认将表单中多个同名字段（如 nm_file）合并为逗号分隔的单个字符串；要真正传递字符串数组，需明确使用 type="array" + @OA\Items(type="string")，并确保前端以多值方式提交（如 nm_file[]=a&nm_file[]=b），而非拼接字符串。

swagger ui 默认将表单中多个同名字段（如 nm_file）合并为逗号分隔的单个字符串；要真正传递字符串数组，需明确使用 type="array" + @oa\items(type="string")，并确保前端以多值方式提交（如 nm_file[]=a&nm_file[]=b），而非拼接字符串。

在 OpenAPI 3.0（通过 swagger-php 注解实现）中，定义 multipart/form-data 请求体中的字符串数组时，关键在于语义准确性和传输协议一致性。你遇到的 nm_file = "string_a,string_b" 问题，并非 Swagger UI 渲染错误，而是后端实际接收到的表单数据格式所致——浏览器原生 <form></form> 提交多个同名 <input name="nm_file"> 时，若未使用 name="nm_file[]" 语法，服务端（如 PHP）通常会将其自动合并为逗号分隔字符串。

✅ 正确做法如下：

OpenAPI 注解应严格声明为字符串数组（无需 object 包裹）：

@OA\Property(
 description="nama file",
 property="nm_file",
 type="array",
 @OA\Items(type="string") // ← 核心：直接声明 items 为 string 类型
),

前端提交必须使用数组式命名（尤其在 Swagger UI Try-it-out 中）：

Generated Photos
Generated Photos是一款提供 AI 生成人脸、全身人物和素材 API 的图库平台。

下载
- ✅ 正确（生成独立表单项）：nm_file[]=string_a 和 nm_file[]=string_b
- ❌ 错误（被合并）：两个 nm_file=string_a 和 nm_file=string_b（无 []）

完整 multipart/form-data 示例注解：

@OA\RequestBody(
 @OA\MediaType(
     mediaType="multipart/form-data",
     @OA\Schema(
         @OA\Property(
             description="nama file",
             property="nm_file",
             type="array",
             @OA\Items(type="string", example="report.pdf")
         ),
         @OA\Property(
             description="file upload",
             property="file[]", // 注意：PHP 风格命名，Swagger UI 支持
             type="array",
             @OA\Items(type="string", format="binary")
         )
     )
 )
)

⚠️ 注意事项：

property="file[]" 是兼容 PHP 的写法，但 OpenAPI 规范中推荐使用 property="file" + type="array"；Swagger UI 会自动处理 [] 后缀。
若后端为 Laravel/Symfony 等框架，确保路由/控制器能正确解析 nm_file 为数组（如 Laravel 中 $request->get('nm_file') 返回 ['string_a', 'string_b']）。
不要误用 @OA\Items(type="object") 包裹字符串——这会导致 Swagger 生成嵌套对象结构（如 [{"someString":"a"}]），与需求不符。

总结：字符串数组的本质是 type="array" + @OA\Items(type="string")，配合前端多值提交机制。Swagger UI 的渲染依赖于规范声明，而非后端行为；务必校验实际 HTTP 请求载荷（如浏览器 DevTools → Network），确认 nm_file 字段是否以多个独立参数形式发送。