NelmioApiDocBundle 4属性方式文件上传问题求助

NelmioApiDocBundle 4 已废弃旧版本的in: 'formData'写法，仅指定multipart/form-data的MediaType无法生效，必须明确定义表单字段结构才能正常生成文件上传控件。

正确的属性配置示例 #

use OpenApi\Attributes as OA;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;

#[OA\Post(
    path: '/api/upload',
    summary: '单文件上传接口',
    requestBody: new OA\RequestBody(
        content: new OA\MediaType(
            mediaType: 'multipart/form-data',
            schema: new OA\Schema(
                type: 'object',
                properties: [
                    // 文件字段必须指定format为binary
                    new OA\Property(
                        property: 'upload_file',
                        type: 'string',
                        format: 'binary',
                        description: '待上传的文件'
                    ),
                    // 可添加其他普通表单字段
                    new OA\Property(
                        property: 'file_desc',
                        type: 'string',
                        description: '文件描述'
                    )
                ],
                // 标记必填字段
                required: ['upload_file']
            )
        )
    ),
    responses: [
        new OA\Response(
            response: 200,
            description: '文件上传成功'
        ),
        new OA\Response(
            response: 400,
            description: '参数错误'
        )
    ]
)]
public function uploadFile(Request $request): JsonResponse
{
    // 从请求中获取上传文件
    $uploadedFile = $request->files->get('upload_file');
    if (!$uploadedFile) {
        return new JsonResponse(['error' => '未上传文件'], 400);
    }

    // 后续文件处理逻辑...
    return new JsonResponse(['status' => 'success', 'filename' => $uploadedFile->getClientOriginalName()]);
}

关键注意事项 #

• 文件字段必须同时设置type: 'string'和format: 'binary'，否则Swagger UI不会显示文件上传控件
• 通过schema的properties定义所有表单字段，包括文件和普通文本字段
• 用required数组标记必填字段，接口文档会自动提示必填项
• 确保控制器方法注入Request对象，通过$request->files->get()获取上传文件

配置检查 #

确认config/packages/nelmio_api_doc.yaml中已开启属性支持：

nelmio_api_doc:
    documentation:
        info:
            title: 项目API文档
            version: 1.0.0
    areas:
        path_patterns:
            - ^/api(?!/doc$) # 排除API文档自身路径

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