update docs

docs/faq.rst

@@ -182,7 +182,7 @@ Q: Areas feature doesn't fit my needs. So how can I group similar endpoints of o
 
 A: Use ``@OA\Tag`` annotation.
 
-.. code-block:: php
+.. code-block:: php-annotations
 
     /**
      * Class BookmarkController
@@ -194,6 +194,18 @@ A: Use ``@OA\Tag`` annotation.
         // ...
     }
 
+.. code-block:: php-attributes
+
+    /**
+     * Class BookmarkController
+     */
+     #[OA\Tag(name: "Bookmarks")]
+    class BookmarkController extends AbstractFOSRestController implements ContextPresetInterface
+    {
+        // ...
+    }
+
+
 Disable Default Section
 -----------------------
 
@@ -217,7 +229,7 @@ do I do that?
 A: By using the ``@OA\Schema`` annotation or attribute with a ``type`` or ``ref``.
 Note, however, that a ``type="object"`` will still read all a models properties.
 
-.. code-block:: php
+.. code-block:: php-annotations
 
     <?php
     use OpenApi\Annotations as OA;
@@ -234,3 +246,18 @@ Note, however, that a ``type="object"`` will still read all a models properties.
         // ...
     }
 
+.. code-block:: php-attributes
+
+    <?php
+    use OpenApi\Attributes as OA;
+    use Nelmio\ApiDocBundle\Attribute\Model;
+
+    /**
+     * or define a `ref`:
+     * #[OA\Schema(ref: "#/components/schemas/SomeRef")
+     */
+    #[OA\Schema(type: "array", items: new OA\Items(ref: new Model(type: SomeEntity::class)))]
+    class SomeCollection implements \IteratorAggregate
+    {
+        // ...
+    }

docs/index.rst

@@ -152,7 +152,7 @@ You can configure global information in the bundle configuration ``documentation
     You may find in the ``.yaml`` files from `SwaggerPHP examples`_.
 
 To document your routes, you can use the SwaggerPHP annotations and the
-``Nelmio\ApiDocBundle\Annotation\Model`` annotation in your controllers::
+``Nelmio\ApiDocBundle\Attribute\Model`` annotation in your controllers::
 
 .. configuration-block::
 
@@ -204,8 +204,8 @@ To document your routes, you can use the SwaggerPHP annotations and the
 
         use AppBundle\Entity\Reward;
         use AppBundle\Entity\User;
-        use Nelmio\ApiDocBundle\Annotation\Model;
-        use Nelmio\ApiDocBundle\Annotation\Security;
+        use Nelmio\ApiDocBundle\Attribute\Model;
+        use Nelmio\ApiDocBundle\Attribute\Security;
         use OpenApi\Attributes as OA;
         use Symfony\Component\Routing\Annotation\Route;
 
@@ -531,7 +531,7 @@ If you want to customize the documentation of an object's property, you can use
 
     .. code-block:: php-annotations
 
-        use Nelmio\ApiDocBundle\Annotation\Model;
+        use Nelmio\ApiDocBundle\Attribute\Model;
         use OpenApi\Annotations as OA;
 
         class User
@@ -562,7 +562,7 @@ 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 Nelmio\ApiDocBundle\Attribute\Model;
         use OpenApi\Attributes as OA;
 
         class User