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）通常会将其自动合并为逗号分隔字符串。

✅ 正确做法如下：

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

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

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

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

3. 完整 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 字段是否以多个独立参数形式发送。