feat(symfony): describe MapUploadedFile property

jankal · jankal · commit 98f462786bf9 · 2025-01-27T10:30:48.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -29,6 +29,7 @@ nelmio_api_doc:
 ```
 
 ## 4.34.0
+* Added support for the `#[MapUploadedFile]` symfony controller argument attribute
 * Changed minimum Symfony version for 7.x from 7.0 to 7.1
 
 ## 4.33.6
diff --git a/docs/symfony_attributes.rst b/docs/symfony_attributes.rst
@@ -61,6 +61,35 @@ Customizing the documentation of the request body can be done by adding the ``#[
             groups: ["create"],
         )
 
+MapUploadedFile
+-------------------------------
+
+Using the `Symfony MapUploadedFile`_ attribute allows NelmioApiDocBundle to automatically generate your request body documentation for your endpoint.
+
+.. versionadded:: 4.37
+
+    The :class:`Symfony\\Component\\HttpKernel\\Attribute\\MapUploadedFile` attribute was introduced in Symfony 7.1.
+
+
+Modify generated documentation
+~~~~~~~
+
+Customizing the documentation of the uploaded file can be done by adding the ``#[OA\RequestBody]`` attribute with the corresponding ``#[OA\MediaType]`` and ``#[OA\Schema]`` to your controller method.
+
+    .. code-block:: php-attributes
+
+        #[OA\RequestBody(
+            description: 'Describe the body',
+            content: [
+                new OA\MediaType('multipart/form-data', new OA\Schema(
+                    properties: [new OA\Property(
+                        property: 'file',
+                        description: 'Describe the file'
+                    )],
+                )),
+            ],
+        )]
+
 Complete example
 ----------------------
 
@@ -90,6 +119,10 @@ Complete example
         use AppBundle\UserDTO;
         use AppBundle\UserQuery;
         use OpenApi\Attributes as OA;
+        use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
+        use Symfony\Component\HttpKernel\Attribute\MapQueryString;
+        use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
+        use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
         use Symfony\Component\Routing\Annotation\Route;
 
         class UserController
@@ -133,6 +166,26 @@ Complete example
             {
                 // ...
             }
+
+            /**
+             * Upload a profile picture
+             */
+            #[Route('/api/users/picture', methods: ['POST'])]
+            #[OA\RequestBody(
+                description: 'Content of the profile picture upload request',
+                content: [
+                    new OA\MediaType('multipart/form-data', new OA\Schema(
+                        properties: [new OA\Property(
+                            property: 'file',
+                            description: 'File containing the profile picture',
+                        )],
+                    )),
+                ],
+            )]
+            public function createUser(#[MapUploadedFile] UploadedFile $picture)
+            {
+                // ...
+            }
         }
 
 Customization
@@ -183,4 +236,5 @@ Make sure to use at least php 8.1 (attribute support) to make use of this functi
 .. _`Symfony MapQueryString`: https://symfony.com/doc/current/controller.html#mapping-the-whole-query-string
 .. _`Symfony MapQueryParameter`: https://symfony.com/doc/current/controller.html#mapping-query-parameters-individually
 .. _`Symfony MapRequestPayload`: https://symfony.com/doc/current/controller.html#mapping-request-payload
+.. _`Symfony MapUploadedFile`: https://symfony.com/doc/current/controller.html#mapping-uploaded-files
 .. _`RouteArgumentDescriberInterface`: https://github.com/DjordyKoert/NelmioApiDocBundle/blob/master/src/RouteDescriber/RouteArgumentDescriber/RouteArgumentDescriberInterface.php
diff --git a/src/DependencyInjection/NelmioApiDocExtension.php b/src/DependencyInjection/NelmioApiDocExtension.php
@@ -29,6 +29,7 @@
 use Nelmio\ApiDocBundle\RouteDescriber\RouteArgumentDescriber\SymfonyMapQueryParameterDescriber;
 use Nelmio\ApiDocBundle\RouteDescriber\RouteArgumentDescriber\SymfonyMapQueryStringDescriber;
 use Nelmio\ApiDocBundle\RouteDescriber\RouteArgumentDescriber\SymfonyMapRequestPayloadDescriber;
+use Nelmio\ApiDocBundle\RouteDescriber\RouteArgumentDescriber\SymfonyMapUploadedFileDescriber;
 use Nelmio\ApiDocBundle\Routing\FilteredRouteCollectionBuilder;
 use OpenApi\Generator;
 use Symfony\Component\Config\FileLocator;
@@ -44,6 +45,7 @@
 use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
 use Symfony\Component\HttpKernel\Attribute\MapQueryString;
 use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
+use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
 use Symfony\Component\Routing\RouteCollection;
 
 final class NelmioApiDocExtension extends Extension implements PrependExtensionInterface
@@ -229,6 +231,12 @@ public function load(array $configs, ContainerBuilder $container): void
                     ->setPublic(false)
                     ->addTag('nelmio_api_doc.route_argument_describer', ['priority' => 0]);
             }
+
+            if (class_exists(MapUploadedFile::class)) {
+                $container->register('nelmio_api_doc.route_argument_describer.map_uploaded_file', SymfonyMapUploadedFileDescriber::class)
+                    ->setPublic(false)
+                    ->addTag('nelmio_api_doc.route_argument_describer', ['priority' => 0]);
+            }
         }
 
         $bundles = $container->getParameter('kernel.bundles');
diff --git a/src/RouteDescriber/RouteArgumentDescriber/SymfonyMapUploadedFileDescriber.php b/src/RouteDescriber/RouteArgumentDescriber/SymfonyMapUploadedFileDescriber.php
@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\RouteDescriber\RouteArgumentDescriber;
+
+use Nelmio\ApiDocBundle\OpenApiPhp\Util;
+use OpenApi\Annotations as OA;
+use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
+use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
+
+final class SymfonyMapUploadedFileDescriber implements RouteArgumentDescriberInterface
+{
+    public const CONTEXT_ARGUMENT_METADATA = 'nelmio_api_doc_bundle.argument_metadata.'.self::class;
+    public const CONTEXT_MODEL_REF = 'nelmio_api_doc_bundle.model_ref.'.self::class;
+
+    public function describe(ArgumentMetadata $argumentMetadata, OA\Operation $operation): void
+    {
+        if (!$attribute = $argumentMetadata->getAttributes(MapUploadedFile::class, ArgumentMetadata::IS_INSTANCEOF)[0] ?? null) {
+            return;
+        }
+
+        $name = $attribute->name ?? $argumentMetadata->getName();
+        $body = Util::getChild($operation, OA\RequestBody::class);
+
+        $mediaType = Util::getCollectionItem($body, OA\MediaType::class, [
+            'mediaType' => 'multipart/form-data'
+        ]);
+
+        /** @var OA\Schema $schema */
+        $schema = Util::getChild($mediaType, OA\Schema::class, [
+            'type' => 'object'
+        ]);
+
+        $property = Util::getCollectionItem($schema, OA\Property::class, ['property' => $name]);
+        Util::modifyAnnotationValue($property, 'type', 'string');
+        Util::modifyAnnotationValue($property, 'format', 'binary');
+    }
+}
diff --git a/tests/Functional/Controller/MapUploadedFileController.php b/tests/Functional/Controller/MapUploadedFileController.php
@@ -0,0 +1,80 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\Tests\Functional\Controller;
+
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\File\UploadedFile;
+use Symfony\Component\HttpKernel\Attribute\MapUploadedFile;
+use Symfony\Component\Routing\Annotation\Route;
+
+class MapUploadedFileController
+{
+    #[Route('/article_map_uploaded_file', methods: ['POST'])]
+    #[OA\Response(response: '200', description: '')]
+    public function createUploadFromMapUploadedFilePayload(
+        #[MapUploadedFile]
+        UploadedFile $upload,
+    ) {
+    }
+
+    #[Route('/article_map_uploaded_file_nullable', methods: ['POST'])]
+    #[OA\Response(response: '200', description: '')]
+    public function createUploadFromMapUploadedFilePayloadNullable(
+        #[MapUploadedFile]
+        ?UploadedFile $upload,
+    ) {
+    }
+
+    #[Route('/article_map_uploaded_file_multiple', methods: ['POST'])]
+    #[OA\Response(response: '200', description: '')]
+    public function createUploadFromMapUploadedFilePayloadMultiple(
+        #[MapUploadedFile]
+        UploadedFile $firstUpload,
+        #[MapUploadedFile]
+        UploadedFile $secondUpload,
+    ) {
+    }
+
+    #[Route('/article_map_uploaded_file_add_to_existing', methods: ['POST'])]
+    #[OA\RequestBody(content: [
+        new OA\MediaType('multipart/form-data', new OA\Schema(
+            properties: [new OA\Property(property: 'existing', type: 'string', format: 'binary')],
+            type: 'object',
+        )),
+    ])]
+    #[OA\Response(response: '200', description: '')]
+    public function createUploadFromMapUploadedFileAddToExisting(
+        #[MapUploadedFile]
+        ?UploadedFile $upload,
+    ) {
+    }
+
+    #[Route('/article_map_uploaded_file_overwrite', methods: ['POST'])]
+    #[OA\RequestBody(
+        description: 'Body if file upload request',
+        content: [
+            new OA\MediaType('multipart/form-data', new OA\Schema(
+                properties: [new OA\Property(
+                    property: 'upload',
+                    description: 'A file',
+                )],
+                type: 'object',
+            )),
+        ],
+    )]
+    #[OA\Response(response: '200', description: '')]
+    public function createUploadFromMapUploadedFileOverwrite(
+        #[MapUploadedFile]
+        ?UploadedFile $upload,
+    ) {
+    }
+}
diff --git a/tests/Functional/ControllerTest.php b/tests/Functional/ControllerTest.php
@@ -178,6 +178,15 @@ public static function provideAttributeTestCases(): \Generator
                 ];
             }
         }
+
+        if (version_compare(Kernel::VERSION, '7.1.0', '>=')) {
+            yield 'Symfony 7.1 MapUploadedFile attribute' => [
+                [
+                    'name' => 'MapUploadedFileController',
+                    'type' => $type,
+                ],
+            ];
+        }
     }
 
     public static function provideAnnotationTestCases(): \Generator
diff --git a/tests/Functional/Fixtures/MapUploadedFileController.json b/tests/Functional/Fixtures/MapUploadedFileController.json

Original file line number	Diff line number	Diff line change
`@@ -178,6 +178,15 @@ public static function provideAttributeTestCases(): \Generator`
`178`	`178`	`];`
`179`	`179`	`}`
`180`	`180`	`}`
	`181`	`+`
	`182`	`+ if (version_compare(Kernel::VERSION, '7.1.0', '>=')) {`
	`183`	`+ yield 'Symfony 7.1 MapUploadedFile attribute' => [`
	`184`	`+ [`
	`185`	`+ 'name' => 'MapUploadedFileController',`
	`186`	`+ 'type' => $type,`
	`187`	`+ ],`
	`188`	`+ ];`
	`189`	`+ }`
`181`	`190`	`}`
`182`	`191`
`183`	`192`	`public static function provideAnnotationTestCases(): \Generator`