[Bug]: Nelmio API Doc cannot scan mixed MapRequestPayload and MapUploadedFile

[natoliverepairsoft]

Version

5.9.2

Description

Description

Nelmio API Doc cannot automatically scan and generate documentation when both MapRequestPayload and MapUploadedFile attributes are used together in the same controller method.

Root Cause

The framework doesn't support automatic introspection of mixed content types (multipart/form-data with file upload + JSON payload). When these two attributes are combined, the documentation generator fails to properly detect and document the endpoint parameters.

Current Workaround

The only workaround is to explicitly add the UploadedFile parameter manually in the controller method signature, even though this is not ideal for automatic API documentation generation.

Example

#[Route("/upload", name: "upload", methods: ["POST"])]
public function upload(
    #[MapRequestPayload] UploadBunnyDto $dto,
    #[MapUploadedFile([
        new Assert\NotBlank(message: 'file is required'),
        new Assert\File(maxSize: '200M')
    ])] UploadedFile $file,
    UploadBunnyUseCase $useCase
): Response
{
    // ...
}

Expected Behavior

Nelmio API Doc should automatically detect and document endpoints that use both MapRequestPayload and MapUploadedFile attributes without requiring manual intervention.

Actual Behavior

The documentation is not generated automatically, and developers must manually specify the parameters as a workaround.

JSON OpenApi

JSON OpenApi

{
    "openapi": "3.0.0",
    "info": {
        "title": "API GED v2",
        "description": "Documentation de l'API GED version 2",
        "version": "2.0.0"
    },
    "paths": {
        "/v2/bunny/upload": {
            "post": {
                "summary": "T\u00e9l\u00e9verser un ficher vers Bunny",
                "operationId": "post_v2_bunny_upload",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "default": {
                        "description": ""
                    }
                }
            }
        },
        "/v2/bunny/delete": {
            "delete": {
                "summary": "Supprimer un fichier de Bunny",
                "operationId": "delete_v2_bunny_delete",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/DeleteBunnyDto"
                            }
                        }
                    }
                },
                "responses": {
                    "default": {
                        "description": ""
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "UploadBunnyDto": {
                "required": [
                    "path",
                    "checksum"
                ],
                "properties": {
                    "path": {
                        "type": "string",
                        "minLength": 1,
                        "pattern": "/(?:[^/\\s]+(?:[ /])?)*, (?!.*TRASH).+"
                    },
                    "checksum": {
                        "type": "string",
                        "maxLength": 64,
                        "minLength": 64,
                        "pattern": "[a-fA-F0-9]{64}"
                    }
                },
                "type": "object"
            },
            "DeleteBunnyDto": {
                "required": [
                    "path",
                    "fileName"
                ],
                "properties": {
                    "path": {
                        "type": "string",
                        "minLength": 1,
                        "pattern": "/(?:[^/\\s]+(?:[ /])?)*/, (?!.*TRASH).+"
                    },
                    "fileName": {
                        "type": "string",
                        "minLength": 1
                    }
                },
                "type": "object"
            }
        },
        "securitySchemes": {
            "X-Security-Token": {
                "type": "apiKey",
                "name": "X-Security-Token",
                "in": "header"
            }
        }
    },
    "security": [
        {
            "X-Security-Token": []
        }
    ]
}

Additional context

No response

[natoliverepairsoft]

Hi everyone! 👋
Happy New Year 2026! 🎉

I forgot to start with a proper greeting, so here it is! I hope you all had wonderful holidays.

I'm reporting this issue/limitation with Nelmio API Doc when using both MapRequestPayload and MapUploadedFile attributes together. Any help or insights would be greatly appreciated!

Thanks in advance for your time and assistance! 🙏

[klkvsk]

Had same problem.
So it seems SymfonyMapUploadedFileDescriber outputs schema in-place, and SymfonyMapRequestPayloadDescriber stores model ref for MapRequestPayloadProcessor to process it later. But MapRequestPayloadProcessor will not overwrite the schema if it exists, so MapUploaded takes priority.

Here's a class I ai-generated to fix it. I have no idea if it covers all edge-cases, but it works. It merges file property and payload model into allOf union in the result.

<?php

namespace App\Framework\NelmioApi;

use Nelmio\ApiDocBundle\OpenApiPhp\Util;
use Nelmio\ApiDocBundle\RouteDescriber\RouteArgumentDescriber\SymfonyMapRequestPayloadDescriber;
use OpenApi\Analysis;
use OpenApi\Annotations as OA;
use OpenApi\Generator;
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

/**
 * Processor that merges MapRequestPayload schema with MapUploadedFile fields.
 *
 * When a controller has both #[MapRequestPayload] and #[MapUploadedFile] attributes,
 * the SymfonyMapUploadedFileDescriber creates a multipart/form-data schema first,
 * and MapRequestPayloadProcessor skips adding the payload schema because content already exists.
 *
 * This processor detects that situation and merges both using allOf.
 */
#[AutoconfigureTag('nelmio_api_doc.swagger.processor')]
class MapUploadedFileProcessor
{
    public function __invoke(Analysis $analysis): void
    {
        /** @var OA\Operation[] $operations */
        $operations = $analysis->getAnnotationsOfType(OA\Operation::class);

        foreach ($operations as $operation) {
            // Check if MapRequestPayload stored a model ref in context
            $payloadModelRef = $operation->_context->{SymfonyMapRequestPayloadDescriber::CONTEXT_MODEL_REF} ?? null;
            if ($payloadModelRef === null) {
                continue;
            }

            // Get the request body
            $requestBody = Util::getChild($operation, OA\RequestBody::class);
            if (Generator::isDefault($requestBody->content)) {
                continue;
            }

            // Check if there's a multipart/form-data media type (set by SymfonyMapUploadedFileDescriber)
            $multipartContent = $requestBody->content[0] ?? null;
            if ($multipartContent === null || $multipartContent->mediaType !== 'multipart/form-data') {
                continue;
            }

            /** @var OA\Schema $existingSchema */
            $existingSchema = Util::getChild($multipartContent, OA\Schema::class);

            // Check if schema already has properties (file fields from SymfonyMapUploadedFileDescriber)
            if (Generator::isDefault($existingSchema->properties)) {
                continue;
            }

            // Build an inline schema containing only the file properties
            $filePropertiesSchema = new OA\Schema([
                '_context'   => Util::createWeakContext($existingSchema->_context),
                'type'       => 'object',
                'properties' => $existingSchema->properties,
            ]);

            // Clear the existing properties and set up allOf to merge payload + file fields
            $existingSchema->properties = Generator::UNDEFINED;
            $existingSchema->allOf = [
                new OA\Schema([
                    '_context' => Util::createWeakContext($existingSchema->_context),
                    'ref'      => $payloadModelRef,
                ]),
                $filePropertiesSchema,
            ];
        }
    }
}

[natoliverepairsoft]

Looks interesting. Waiting for maintainers to respond.

[Davidshb]

Here is some leads. As @klkvsk mentioned it is possible to use allOf.

    #[OA\Post(
        operationId: 'create incident',
        requestBody: new OA\RequestBody(
            content: new OA\MediaType(
                mediaType: 'multipart/form-data',
                schema: new OA\Schema(
                    allOf: [new OA\Schema(ref: new Model(type: IncidentInput::class))]
                )
            )
        )
    )]
    #[OA\Response(
        response: Response::HTTP_CREATED,
        description: 'incident created'
    )]
    #[Route('/incidents', name: 'create_incident', methods: Request::METHOD_POST)]
    public function createIncident(
        Uuid $projectId,
        EntityManagerInterface $entityManager,
        #[MapRequestPayload(acceptFormat: 'form')]
        IncidentInput $incidentInput,
        #[MapUploadedFile]
        UploadedFile $media,
        #[MapUploadedFile]
        ?UploadedFile $voiceNote
    ): Response {
         ...
    }