Merge branch 'master' into 5.x

# Conflicts:
#	src/DependencyInjection/NelmioApiDocExtension.php
#	src/ModelDescriber/Annotations/AnnotationsReader.php
#	src/ModelDescriber/ObjectModelDescriber.php
#	tests/Functional/Controller/ApiController81.php
#	tests/Functional/Controller/JMSController81.php
#	tests/Functional/ControllerTest.php

Author: DjordyKoert

CHANGELOG.md

@@ -1,5 +1,23 @@
 # CHANGELOG
 
+## 4.38.0
+* Added a `#[Ignore]` attribute that allows a property to be excluded from the generated schema.
+```php
+<?php
+
+use Nelmio\ApiDocBundle\Attribute\Ignore;
+
+class Foo
+{
+    #[Ignore]
+    private string $ignoredProperty;
+}
+```
+* Added support for the `#[MapUploadedFile]` symfony controller argument attribute
+
+## 4.37.0
+* Added Stoplight as an alternative UI option. https://stoplight.io/open-source/elements.
+
 ## 4.36.1
 - Passing an array key `value` with a list of strings to the `Areas` annotation/attribute is deprecated. Pass the list of strings directly.
 ```diff

README.md

@@ -1,10 +1,11 @@
 NelmioApiDocBundle
 ==================
 
-[![Build Status](https://img.shields.io/github/actions/workflow/status/nelmio/NelmioApiDocBundle/continuous-integration.yml?branch=master&style=flat-square)](https://github.com/nelmio/NelmioApiDocBundle/actions?query=workflow:CI) 
-[![Total Downloads](https://poser.pugx.org/nelmio/api-doc-bundle/downloads)](https://packagist.org/packages/nelmio/api-doc-bundle)
-[![Latest Stable
-Version](https://poser.pugx.org/nelmio/api-doc-bundle/v/stable)](https://packagist.org/packages/nelmio/api-doc-bundle)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/nelmio/NelmioApiDocBundle/continuous-integration.yml?branch=master&style=flat-square)](https://github.com/nelmio/NelmioApiDocBundle/actions?query=workflow:CI)
+[![Codecov](https://img.shields.io/codecov/c/github/nelmio/NelmioApiDocBundle?branch=master&style=flat-square)](https://app.codecov.io/gh/nelmio/NelmioApiDocBundle)
+[![Total Downloads](https://img.shields.io/packagist/dt/nelmio/api-doc-bundle?style=flat-square)](https://packagist.org/packages/nelmio/api-doc-bundle)
+[![Latest Stable Version](https://img.shields.io/packagist/v/nelmio/api-doc-bundle?label=stable&style=flat-square)](https://packagist.org/packages/nelmio/api-doc-bundle)
+[![PHP Version](https://img.shields.io/packagist/dependency-v/nelmio/api-doc-bundle/PHP?style=flat-square)](https://packagist.org/packages/nelmio/api-doc-bundle)
 
 The **NelmioApiDocBundle** bundle allows you to generate a decent documentation
 for your APIs.

config/services.xml

@@ -21,6 +21,11 @@
             <argument type="string">redocly</argument>
         </service>
 
+        <service id="nelmio_api_doc.controller.stoplight" class="Nelmio\ApiDocBundle\Controller\SwaggerUiController" public="true">
+            <argument type="service" id="nelmio_api_doc.render_docs" />
+            <argument type="string">stoplight</argument>
+        </service>
+
         <service id="nelmio_api_doc.controller.swagger" alias="nelmio_api_doc.controller.swagger_json" public="true" />
 
         <service id="nelmio_api_doc.controller.swagger_json" class="Nelmio\ApiDocBundle\Controller\DocumentationController" public="true">

docs/areas.rst

@@ -53,6 +53,13 @@ Then update your routing to be able to access your different documentations:
     #    methods: GET
     #    defaults: { _controller: nelmio_api_doc.controller.redocly, area: default }
 
+    # With Stoplight
+    # app/config/routing.yaml
+    #app.stoplight:
+    #    path: /api/doc/{area}
+    #    methods: GET
+    #    defaults: { _controller: nelmio_api_doc.controller.stoplight, area: default }
+
     # To expose them as JSON
     #app.swagger.areas:
     #    path: /api/doc/{area}.json

docs/commands.rst

@@ -38,6 +38,7 @@ or configure UI configuration, use the ``--html-config`` option.
 - ``swagger_ui_config`` - `configure Swagger UI`_
     - ``"supportedSubmitMethods":[]`` disables the sandbox
 - ``redocly_config`` - `configure Redocly`_
+- ``stoplight_config`` - `configure Stoplight`_
 
 .. code-block:: bash
 

docs/configuration_reference.rst

@@ -40,6 +40,8 @@ The bundle configuration is stored under the ``nelmio_api_doc`` key in your appl
             swagger_ui_config: []
             # https://redocly.com/docs/redoc/config/
             redocly_config: []
+            # https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
+            stoplight_config: []
         # Filter the routes that are documented
         areas:
             default:
@@ -157,7 +159,7 @@ html_config
 
 **type**: ``dictionary``
 **default**: ``[]``
-**allowed keys**: ``assets_mode``, ``swagger_ui_config``, ``redocly_config``
+**allowed keys**: ``assets_mode``, ``swagger_ui_config``, ``redocly_config``, ``stoplight_config``
 
 UI configuration options.
 
@@ -172,6 +174,12 @@ UI configuration options.
                 swagger_ui_config: []
                 # https://redocly.com/docs/redoc/config/
                 redocly_config: []
+                # https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
+                stoplight_config: []
+
+.. versionadded:: 4.37
+
+    The `stoplight_config` option was added in 4.37.
 
 areas
 ~~~~~

docs/index.rst

@@ -73,6 +73,14 @@ By default, only routes under ``/api`` are documented. Update the regexp at ``ne
             methods: GET
             defaults: { _controller: nelmio_api_doc.controller.redocly }
 
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        app.stoplight:
+            path: /api/doc
+            methods: GET
+            defaults: { _controller: nelmio_api_doc.controller.stoplight }
+
     If you also want to expose it in JSON, register this route:
 
     .. code-block:: yaml

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

phpstan-baseline.neon

@@ -7,7 +7,7 @@ parameters:
 
 		-
 			message: "#^Call to method render\\(\\) on an unknown class Twig_Environment\\.$#"
-			count: 2
+			count: 3
 			path: src/Render/Html/HtmlOpenApiRenderer.php
 
 		-

phpstan.dist.neon

@@ -29,6 +29,6 @@ parameters:
     universalObjectCratesClasses:
         - OpenApi\Context
     treatPhpDocTypesAsCertain: false
-    checkGenericClassInNonGenericObjectType: false
     ignoreErrors:
+        - identifier: missingType.generics
         - '#^Property class@anonymous/tests/.* has no type specified.$#'