[Docs] Add PHP Attributes examples (#1985)

* [Docs] Add PHP Attributes examples

* Fix namespaces

Resources/doc/index.rst

@@ -17,6 +17,8 @@ This bundle supports *Symfony* route requirements, PHP annotations, `Swagger-Php
 For models, it supports the `Symfony serializer`_ , the `JMS serializer`_ and the `willdurand/Hateoas`_ library.
 It does also support `Symfony form`_ types.
 
+Attributes are supported from version 4.7 and PHP 8.1.
+
 Migrate from 3.x to 4.0
 -----------------------
 
@@ -137,6 +139,10 @@ You can configure global information in the bundle configuration ``documentation
 To document your routes, you can use the SwaggerPHP annotations and the
 ``Nelmio\ApiDocBundle\Annotation\Model`` annotation in your controllers::
 
+.. configuration-block::
+
+    .. code-block:: php-annotations
+    
         namespace AppBundle\Controller;
 
         use AppBundle\Entity\User;
@@ -177,6 +183,48 @@ To document your routes, you can use the SwaggerPHP annotations and the
             }
         }
     
+    .. code-block:: php-attributes
+    
+        namespace AppBundle\Controller;
+
+        use AppBundle\Entity\User;
+        use AppBundle\Entity\Reward;
+        use Nelmio\ApiDocBundle\Annotation\Model;
+        use Nelmio\ApiDocBundle\Annotation\Security;
+        use OpenApi\Attributes as OA;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class UserController
+        {
+            /**
+             * List the rewards of the specified user.
+             *
+             * This call takes into account all confirmed awards, but not pending or refused awards.
+             */
+            #[Route('/api/{user}/rewards', methods=['GET'])]
+            #[OA\Response(
+                response: 200,
+                description: 'Returns the rewards of an user',
+                content: new OA\JsonContent(
+                    type: 'array', 
+                    items: new OA\Items(ref: new Model(type: AlbumDto::class, groups: ['full']))
+                )
+            )]
+            #[OA\Parameter(
+                name: 'order',
+                in: 'query',
+                description: 'The field used to order rewards',
+                schema: new OA\Schema(type: 'string')
+            )]
+            #[OA\Tag(name: 'rewards')]
+            #[Security(name: 'Bearer')]
+            public function fetchUserRewardsAction(User $user)
+            {
+                // ...
+            }
+        }
+    
+
 The normal PHPdoc block on the controller method is used for the summary and description.
 
 .. tip::
@@ -199,6 +247,10 @@ This annotation has two options:
 
 * ``type`` to specify your model's type::
 
+.. configuration-block::
+
+    .. code-block:: php-annotations
+    
         /**
          * @OA\Response(
          *     response=200,
@@ -206,8 +258,21 @@ This annotation has two options:
          * )
          */
 
+    .. code-block:: php-attributes
+    
+        #[OA\Response(
+            response: 200,
+            description: 'Successful response',
+            content: new Model(type: User::class)
+        )]
+
 * ``groups`` to specify the serialization groups used to (de)serialize your model::
 
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
          /**
          * @OA\Response(
          *     response=200,
@@ -215,6 +280,14 @@ This annotation has two options:
          * )
          */
 
+    .. code-block:: php-attributes
+    
+        #[OA\Response(
+            response: 200,
+            description: 'Successful response',
+            content: new Model(type: User::class, groups: ['non_sensitive_data'])
+        )]
+
  .. tip::
 
      When used at the root of ``@OA\Response`` and ``@OA\Parameter``, ``@Model`` is automatically nested
@@ -224,6 +297,10 @@ This annotation has two options:
 
      To use ``@Model`` directly within a ``@OA\Schema``, ``@OA\Items`` or ``@OA\Property``, you have to use the ``$ref`` field::
 
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
          /**
           * @OA\Response(
           *     @OA\JsonContent(ref=@Model(type=User::class))
@@ -238,6 +315,23 @@ This annotation has two options:
           * ))
           */
 
+    .. code-block:: php-attributes
+
+        #[OA\Response(
+            content: new OA\JsonContent(ref: new Model(type: User::class))
+        )]
+         /**
+          * or
+          */
+        #[OA\Response(
+            content: new OA\XmlContent(example: new OA\Schema(
+                type: 'object',
+                properties: [
+                    new OA\Property(property: 'foo', ref: new Model(type: FooClass::class))
+                ]
+            ))
+        )]
+
 Symfony Form types
 ~~~~~~~~~~~~~~~~~~
 
@@ -288,8 +382,16 @@ General PHP objects
 
     .. code-block:: php
 
+        .. configuration-block::
+
+            .. code-block:: php-annotations
+
                 @OA\Schema(ref=@Model(type="App\Response\ItemResponse", groups=["Default"])),
 
+            .. code-block:: php-attributes
+
+                #[OA\Schema(ref: new Model(type: App\Response\ItemResponse::class, groups: ['Default']))]
+
     It will generate two different component schemas (ItemResponse, ItemResponse2), even though Default and blank are the same. This is by design.
 
     In case you prefer using the `Symfony PropertyInfo component`_ (you
@@ -306,6 +408,11 @@ General PHP objects
 
 If you want to customize the documentation of an object's property, you can use ``@OA\Property``::
 
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+            
         use Nelmio\ApiDocBundle\Annotation\Model;
         use OpenApi\Annotations as OA;
 
@@ -335,6 +442,31 @@ If you want to customize the documentation of an object's property, you can use
             }
         }
 
+    .. code-block:: php-attributes
+            
+        use Nelmio\ApiDocBundle\Annotation\Model;
+        use OpenApi\Attributes as OA;
+
+        class User
+        {
+            /**
+             * @var int
+             */
+            #[OA\Property(description: 'The unique identifier of the user.')]
+            public $id;
+
+            #[OA\Property(type: 'string', maxLength: 255)]
+            public $username;
+
+            #[OA\Property(ref: new Model(type: User::class))]
+            public $friend;
+
+            #[OA\Property(description: 'This is my coworker!')]
+            public setCoworker(User $coworker) {
+                // ...
+            }
+        }
+
 See the `OpenAPI 3.0 specification`__ to see all the available fields of ``@OA\Property``.
 
 __ https://swagger.io/specification/