Add Symfony attribute describers

.doctor-rst.yaml

@@ -53,10 +53,10 @@ rules:
 
     #   master
     versionadded_directive_major_version:
-        major_version: 5
+        major_version: 6
 
     versionadded_directive_min_version:
-        min_version: '5.0'
+        min_version: '6.0'
 
     deprecated_directive_major_version:
         major_version: 5
@@ -71,4 +71,4 @@ whitelist:
     lines:
         - '.. code-block:: twig'
         - '// bin/console'
-        - '.. code-block:: php'
+        - '.. code-block:: php'

DependencyInjection/NelmioApiDocExtension.php

@@ -30,6 +30,9 @@
 use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\DependencyInjection\ServiceLocator;
+use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
+use Symfony\Component\HttpKernel\Attribute\MapQueryString;
+use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
 use Symfony\Component\HttpKernel\DependencyInjection\Extension;
 use Symfony\Component\Routing\RouteCollection;
 
@@ -159,6 +162,15 @@ public function load(array $configs, ContainerBuilder $container): void
                 ->setArgument(1, $config['media_types']);
         }
 
+        if (
+            PHP_VERSION_ID > 80100
+            && class_exists(MapRequestPayload::class)
+            && class_exists(MapQueryParameter::class)
+            && class_exists(MapQueryString::class)
+        ) {
+            $loader->load('symfony.xml');
+        }
+
         $bundles = $container->getParameter('kernel.bundles');
         if (!isset($bundles['TwigBundle']) || !class_exists('Symfony\Component\Asset\Packages')) {
             $container->removeDefinition('nelmio_api_doc.controller.swagger_ui');

Resources/config/symfony.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" ?>
+<container xmlns="http://symfony.com/schema/dic/services"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+    <services>
+        <instanceof id="Nelmio\ApiDocBundle\RouteDescriber\SymfonyAnnotationDescriber\SymfonyAnnotationDescriber">
+            <tag name="nelmio_api_doc.symfony_annotation_describer" />
+        </instanceof>
+
+        <service id="nelmio_api_doc.symfony_annotation_describer.map_query_string" class="Nelmio\ApiDocBundle\RouteDescriber\SymfonyAnnotationDescriber\SymfonyMapQueryStringDescriber" public="false" >
+            <argument type="tagged_iterator" tag="nelmio_api_doc.model_describer"/>
+        </service>
+
+        <service id="nelmio_api_doc.symfony_annotation_describer.map_query_parameter" class="Nelmio\ApiDocBundle\RouteDescriber\SymfonyAnnotationDescriber\SymfonyMapQueryParameterDescriber" public="false" />
+
+        <service id="nelmio_api_doc.symfony_annotation_describer.map_request_payload" class="Nelmio\ApiDocBundle\RouteDescriber\SymfonyAnnotationDescriber\SymfonyMapRequestPayloadDescriber" public="false" />
+
+        <service id="nelmio_api_doc.route_describers.symfony" class="Nelmio\ApiDocBundle\RouteDescriber\SymfonyDescriber" public="false">
+            <tag name="nelmio_api_doc.route_describer" priority="-225" />
+            <argument type="tagged_iterator" tag="nelmio_api_doc.symfony_annotation_describer"/>
+        </service>
+    </services>
+</container>

Resources/doc/index.rst

@@ -7,7 +7,7 @@ OpenAPI (Swagger) format and provides a sandbox to interactively experiment with
 What's supported?
 -----------------
 
-This bundle supports *Symfony* route requirements, PHP annotations, `Swagger-Php`_ annotations,
+This bundle supports *Symfony* route requirements, *Symfony* request mapping (:doc:`symfony_attributes`), PHP annotations, `Swagger-Php`_ annotations,
 `FOSRestBundle`_ annotations and applications using `Api-Platform`_.
 
 .. _`Swagger-Php`: https://github.com/zircote/swagger-php
@@ -239,6 +239,12 @@ The normal PHPDoc block on the controller method is used for the summary and des
     However, unlike in those examples, when using this bundle you don't need to specify paths and you can easily document models as well as some
     other properties described below as they can be automatically be documented using the Symfony integration.
 
+.. tip::
+
+    **NelmioApiDocBundle** understands **symfony's** controller attributes.
+    Using these attributes inside your controller allows this bundle to automatically create the necessary documentation.
+    More information can be found here: :doc:`symfony_attributes`.
+
 Use Models
 ----------
 
@@ -576,6 +582,7 @@ If you need more complex features, take a look at:
     commands
     faq
     security
+    symfony_attributes
 
 .. _`SwaggerPHP examples`: https://github.com/zircote/swagger-php/tree/master/Examples
 .. _`Symfony PropertyInfo component`: https://symfony.com/doc/current/components/property_info.html

Resources/doc/symfony_attributes.rst

@@ -0,0 +1,159 @@
+Symfony attributes
+================================
+
+NelmioApiDocBundle has the ability to automatically create documentation from **symfony** controller attributes.
+
+MapQueryString
+-------------------------------
+
+Using the `Symfony MapQueryString`_ attribute allows NelmioApiDocBundle to automatically generate your query parameter documentation for your endpoint from your object.
+
+.. versionadded:: 6.3
+
+    The :class:`Symfony\\Component\\HttpKernel\\Attribute\\MapQueryString` attribute was introduced in Symfony 6.3.
+
+Modify generated documentation
+~~~~~~~
+
+Modifying the generated documentation can easily by done in two ways, by:
+* Customizing the documentation of an object's property (``#[OA\Property]`` attribute)
+* Customizing the documentation of a query parameter (``#[OA\Parameter]`` attribute)
+
+Customizing the documentation of a specific query parameter can be done by adding the ``#[OA\Parameter]`` attribute to your controller method.
+Make sure that the ``in`` property is set to ``'query'`` and that the ``name`` property is set to the object's property name which you want to customize.
+
+    .. code-block:: php-attributes
+
+        #[OA\Parameter(
+            name: 'id',
+            description: 'Some additional parameter description',
+            in: 'query',
+        )]
+
+MapQueryParameter
+-------------------------------
+
+Using the `Symfony MapQueryParameter`_ attribute allows NelmioApiDocBundle to automatically generate your query parameter documentation for your endpoint.
+
+.. versionadded:: 6.3
+
+    The :class:`Symfony\\Component\\HttpKernel\\Attribute\\MapQueryParameter` attribute was introduced in Symfony 6.3.
+
+
+Modify generated documentation
+~~~~~~~
+
+Customizing the documentation of the query parameter can be done by adding the ``#[OA\Parameter]`` attribute to your controller method.
+Make sure that the ``in`` property is set to ``'query'`` and that the ``name`` property is set to the name of the controller method parameter.
+
+    .. code-block:: php-attributes
+
+        #[OA\Parameter(
+            name: 'id',
+            description: 'Some additional parameter description',
+            in: 'query',
+        )]
+
+MapRequestPayload
+-------------------------------
+
+Using the `Symfony MapRequestPayload`_ attribute allows NelmioApiDocBundle to automatically generate your request body documentation for your endpoint.
+
+.. versionadded:: 6.3
+
+    The :class:`Symfony\\Component\\HttpKernel\\Attribute\\MapRequestPayload` attribute was introduced in Symfony 6.3.
+
+
+Modify generated documentation
+~~~~~~~
+
+Customizing the documentation of the request body can be done by adding the ``#[OA\RequestBody]`` attribute to your controller method.
+
+    .. code-block:: php-attributes
+
+        #[OA\RequestBody(
+            groups: ["create"],
+        )
+
+Complete example
+----------------------
+
+    .. code-block:: php-attributes
+
+        class UserQuery
+        {
+            public int $userId;
+        }
+
+    .. code-block:: php-attributes
+
+        use Symfony\Component\Serializer\Annotation\Groups;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class UserDto
+        {
+            #[Groups(["default", "create", "update"])]
+            #[Assert\NotBlank(groups: ["default", "create"])]
+            public string $username;
+        }
+
+    .. code-block:: php-attributes
+
+        namespace AppBundle\Controller;
+
+        use AppBundle\UserDTO;
+        use AppBundle\UserQuery;
+        use OpenApi\Attributes as OA;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class UserController
+        {
+            /**
+             * Find user with MapQueryString.
+             */
+            #[Route('/api/users', methods: ['GET'])]
+            #[OA\Parameter(
+                name: 'userId',
+                description: 'Id of the user to find',
+                in: 'query',
+            )]
+            public function findUser(#[MapQueryString] UserQuery $userQuery)
+            {
+                // ...
+            }
+
+            /**
+             * Find user with MapQueryParameter.
+             */
+            #[Route('/api/users/v2', methods: ['GET'])]
+            #[OA\Parameter(
+                name: 'userId',
+                description: 'Id of the user to find',
+                in: 'query',
+            )]
+            public function findUserV2(#[MapQueryParameter] int $userId)
+            {
+                // ...
+            }
+
+            /**
+             * Create a new user.
+             */
+            #[Route('/api/users', methods: ['POST'])]
+            #[OA\RequestBody(
+                groups: ['create'],
+            )]
+            public function createUser(#[MapRequestPayload] UserDTO $user)
+            {
+                // ...
+            }
+        }
+
+Disclaimer
+----------------------
+
+Make sure to use at least php 8 (annotations) to make use of this functionality
+
+.. _`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

RouteDescriber/SymfonyAnnotationDescriber/SymfonyAnnotationDescriber.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nelmio\ApiDocBundle\RouteDescriber\SymfonyAnnotationDescriber;
+
+use OpenApi\Annotations as OA;
+use ReflectionParameter;
+
+interface SymfonyAnnotationDescriber
+{
+    public function supports(ReflectionParameter $parameter): bool;
+
+    public function describe(OA\OpenApi $api, OA\Operation $operation, ReflectionParameter $parameter): void;
+}

RouteDescriber/SymfonyAnnotationDescriber/SymfonyAnnotationHelper.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nelmio\ApiDocBundle\RouteDescriber\SymfonyAnnotationDescriber;
+
+use OpenApi\Annotations as OA;
+use OpenApi\Generator;
+use ReflectionParameter;
+
+final class SymfonyAnnotationHelper
+{
+    /**
+     * @param class-string<T> $attribute
+     *
+     * @return T|null
+     *
+     * @template T of object
+     */
+    public static function getAttribute(ReflectionParameter $parameter, string $attribute): ?object
+    {
+        if ($attribute = $parameter->getAttributes($attribute, \ReflectionAttribute::IS_INSTANCEOF)) {
+            return $attribute[0]->newInstance();
+        }
+
+        return null;
+    }
+
+    public static function describeCommonSchemaFromParameter(OA\Schema $schema, ReflectionParameter $parameter): void
+    {
+        if ($parameter->isDefaultValueAvailable()) {
+            self::modifyAnnotationValue($schema, 'default', $parameter->getDefaultValue());
+        }
+
+        if ($parameter->getType()->isBuiltin()) {
+            $type = $parameter->getType()->getName();
+
+            if (in_array($type, ['int', 'integer'], true)) {
+                $type = 'integer';
+            }
+
+            self::modifyAnnotationValue($schema, 'type', $type);
+        }
+    }
+
+    public static function modifyAnnotationValue(OA\AbstractAnnotation $parameter, string $property, $value): void
+    {
+        if (!Generator::isDefault($parameter->{$property})) {
+            return;
+        }
+
+        $parameter->{$property} = $value;
+    }
+}

RouteDescriber/SymfonyAnnotationDescriber/SymfonyMapQueryParameterDescriber.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nelmio\ApiDocBundle\RouteDescriber\SymfonyAnnotationDescriber;
+
+use Nelmio\ApiDocBundle\OpenApiPhp\Util;
+use OpenApi\Annotations as OA;
+use ReflectionParameter;
+use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
+
+final class SymfonyMapQueryParameterDescriber implements SymfonyAnnotationDescriber
+{
+    public function supports(ReflectionParameter $parameter): bool
+    {
+        if (!SymfonyAnnotationHelper::getAttribute($parameter, MapQueryParameter::class)) {
+            return false;
+        }
+
+        return $parameter->hasType();
+    }
+
+    public function describe(OA\OpenApi $api, OA\Operation $operation, ReflectionParameter $parameter): void
+    {
+        $attribute = SymfonyAnnotationHelper::getAttribute($parameter, MapQueryParameter::class);
+
+        $operationParameter = Util::getOperationParameter($operation, $attribute->name ?? $parameter->getName(), 'query');
+
+        SymfonyAnnotationHelper::modifyAnnotationValue($operationParameter, 'required', !($parameter->isDefaultValueAvailable() || $parameter->allowsNull()));
+
+        /** @var OA\Schema $schema */
+        $schema = Util::getChild($operationParameter, OA\Schema::class);
+
+        if (FILTER_VALIDATE_REGEXP === $attribute->filter) {
+            SymfonyAnnotationHelper::modifyAnnotationValue($schema, 'pattern', $attribute->options['regexp']);
+        }
+
+        SymfonyAnnotationHelper::describeCommonSchemaFromParameter($schema, $parameter);
+    }
+}