feat: 4.x annotation to attribute migration 5.x (#2369)

| Q | A |

|---------------|---------------------------------------------------------------------------------------------------------------------------|
| Bug fix? | no |
| New feature? | no <!-- please update src/**/CHANGELOG.md files --> |
| Deprecations? | yes                                                  |

Migration for annotations to attributes
#2368 (comment)

CHANGELOG.md

@@ -1,5 +1,21 @@
 # CHANGELOG
 
+## 4.32.3
+
+* Deprecated `Nelmio\ApiDocBundle\Annotation` namespace in favor of `Nelmio\ApiDocBundle\Attribute` namespace in preparation for 5.x. Consider upgrading to the new attribute syntax.
+```diff 
+- use Nelmio\ApiDocBundle\Annotation\Areas;
+- use Nelmio\ApiDocBundle\Annotation\Model;
+- use Nelmio\ApiDocBundle\Annotation\Operation;
+- use Nelmio\ApiDocBundle\Annotation\Security;
+
++ use Nelmio\ApiDocBundle\Attribute\Areas;
++ use Nelmio\ApiDocBundle\Attribute\Model;
++ use Nelmio\ApiDocBundle\Attribute\Operation;
++ use Nelmio\ApiDocBundle\Attribute\Security;
+```
+
+
 ## 4.32.0
 
 * Added support to configure `options` and `serializationContext` via `nelmio_api_doc.models.names`.

docs/alternative_names.rst

@@ -29,7 +29,7 @@ In this case the class ``App\Entity\User`` will be aliased into:
 
 .. tip::
 
-    This allows to use normal references instead of ``@Model``. Notably, you can specify
+    This allows to use normal references instead of ``#[Model]``. Notably, you can specify
     the groups used for a model once in config and then refer to its alternative name:
 
     .. code-block:: yaml
@@ -38,14 +38,26 @@ In this case the class ``App\Entity\User`` will be aliased into:
             models:
                 names: [ { alias: MyModel, type: App\MyModel, groups: [light] }]
 
-    .. code-block:: php
+    .. configuration-block::
 
-        class HomeController
-        {
-            /**
-             * @OA\Response(response=200, @OA\JsonContent(ref="#/components/schemas/MyModel"))
-             */
-            public function indexAction()
+        .. code-block:: php-annotations
+
+            class HomeController
             {
+                /**
+                 * @OA\Response(response=200, @OA\JsonContent(ref="#/components/schemas/MyModel"))
+                 */
+                public function indexAction()
+                {
+                }
             }
-        }
+
+        .. code-block:: php-attributes
+
+            class HomeController
+            {
+                #[OA\Response(response: 200, content: new OA\JsonContent(ref: "#/components/schemas/MyModel"))]
+                public function indexAction()
+                {
+                }
+            }

docs/areas.rst

@@ -62,12 +62,12 @@ Then update your routing to be able to access your different documentations:
 
 That's all! You can now access ``/api/doc/internal``, ``/api/doc/commercial`` and ``/api/doc/store``.
 
-Use annotations to filter documented routes in each area
+Use attributes to filter documented routes in each area
 --------------------------------------------------------
 
-You can use the `@Areas` annotation inside your controllers to define your routes' areas.
+You can use the ``#[Areas]`` attribute inside your controllers to define your routes' areas.
 
-First, you need to define which areas will use the`@Areas` annotations to filter
+First, you need to define which areas will use the`#[Areas]` attributes to filter
 the routes that should be documented:
 
 .. code-block:: yaml
@@ -79,20 +79,45 @@ the routes that should be documented:
             internal:
                 with_annotation: true
 
-Then add the annotation before your controller or action::
+Then add the attribute/annotation before your controller or action::
 
-    use Nelmio\Annotations as Nelmio;
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        use Nelmio\Annotation as Nelmio;
+
+        /**
+         * @Nelmio\Areas({"internal"}) => All actions in this controller are documented under the 'internal' area
+         */
+        class MyController
+        {
+            /**
+             * @Nelmio\Areas({"internal"}) => This action is documented under the 'internal' area
+             */
+            public function index()
+            {
+               ...
+            }
+        }
+
+    .. code-block:: php-attributes
+
+        use Nelmio\Attribute as Nelmio;
 
-    /**
-     * @Nelmio\Areas({"internal"}) => All actions in this controller are documented under the 'internal' area
-     */
-    class MyController
-    {
         /**
-         * @Nelmio\Areas({"internal"}) => This action is documented under the 'internal' area
+         * All actions in this controller are documented under the 'internal' area
          */
-        public function index()
+        #[Nelmio\Areas(["internal"])]
+        class MyController
         {
-           ...
+            /**
+             * This action is documented under the 'internal' area
+             */
+            #[Nelmio\Areas(["internal"])]
+            public function index()
+            {
+               ...
+            }
         }
-    }
+

docs/faq.rst

@@ -180,19 +180,33 @@ Endpoints grouping
 
 Q: Areas feature doesn't fit my needs. So how can I group similar endpoints of one or more controllers in a separate section in the documentation?
 
-A: Use ``@OA\Tag`` annotation.
+A: Use ``#[OA\Tag]`` attribute.
 
-.. code-block:: php
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        /**
+         * Class BookmarkController
+         *
+         * @OA\Tag(name="Bookmarks")
+         */
+        class BookmarkController extends AbstractFOSRestController implements ContextPresetInterface
+        {
+            // ...
+        }
+
+    .. code-block:: php-attributes
+
+        /**
+         * Class BookmarkController
+         */
+        #[OA\Tag(name: "Bookmarks")]
+        class BookmarkController extends AbstractFOSRestController implements ContextPresetInterface
+        {
+            // ...
+        }
 
-    /**
-     * Class BookmarkController
-     *
-     * @OA\Tag(name="Bookmarks")
-     */
-    class BookmarkController extends AbstractFOSRestController implements ContextPresetInterface
-    {
-        // ...
-    }
 
 Disable Default Section
 -----------------------
@@ -214,23 +228,38 @@ Overriding a Form or Plain PHP Object Schema Type
 Q: I'd like to define a PHP object or form with a type other any ``object``, how
 do I do that?
 
-A: By using the ``@OA\Schema`` annotation or attribute with a ``type`` or ``ref``.
+A: By using the ``#[OA\Schema]`` attribute/annotation with a ``type`` or ``ref``.
 Note, however, that a ``type="object"`` will still read all a models properties.
 
-.. code-block:: php
-
-    <?php
-    use OpenApi\Annotations as OA;
-    use Nelmio\ApiDocBundle\Annotation\Model;
-
-    /**
-     * @OA\Schema(type="array", @OA\Items(ref=@Model(type=SomeEntity::class)))
-     *
-     * or define a `ref`:
-     * @OA\Schema(ref="#/components/schemas/SomeRef")
-     */
-    class SomeCollection implements \IteratorAggregate
-    {
-        // ...
-    }
-
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        use Nelmio\ApiDocBundle\Annotation\Model;
+        use OpenApi\Annotations as OA;
+
+        /**
+         * @OA\Schema(type="array", @OA\Items(ref=@Model(type=SomeEntity::class)))
+         *
+         * or define a `ref`:
+         * @OA\Schema(ref="#/components/schemas/SomeRef")
+         */
+        class SomeCollection implements \IteratorAggregate
+        {
+            // ...
+        }
+
+    .. code-block:: php-attributes
+
+        use Nelmio\ApiDocBundle\Attribute\Model;
+        use OpenApi\Attributes as OA;
+
+        /**
+         * 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

@@ -105,7 +105,7 @@ How does this bundle work?
 --------------------------
 
 It generates an OpenAPI documentation from your Symfony app thanks to
-**Describers**. One extracts data from SwaggerPHP annotations, one from your
+**Describers**. One extracts data from SwaggerPHP attributes/annotations, one from your
 routes, etc.
 
 If you configured the ``app.swagger_ui`` route above, you can browse your
@@ -151,8 +151,8 @@ You can configure global information in the bundle configuration ``documentation
     This configuration field can more generally be used to store your documentation as yaml.
     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::
+To document your routes, you can use the SwaggerPHP attributes/annotations and the
+``#[Model]`` attribute/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;
 
@@ -244,7 +244,7 @@ The normal PHPDoc block on the controller method is used for the summary and des
 
 .. tip::
 
-    Examples of using the annotations can be found in `SwaggerPHP examples`_.
+    Examples of using the attributes/annotations can be found in `SwaggerPHP examples`_.
     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.
 
@@ -257,14 +257,14 @@ The normal PHPDoc block on the controller method is used for the summary and des
 Use Models
 ----------
 
-As shown in the example above, the bundle provides the ``@Model`` annotation.
+As shown in the example above, the bundle provides the ``#[Model]`` attribute.
 Use it instead of a definition reference and the bundle will deduce your model properties.
 
 .. note::
 
     A model can be a Symfony form type, a Doctrine ORM entity or a general PHP object.
 
-This annotation has two options:
+This attribute has two options:
 
 * ``type`` to specify your model's type::
 
@@ -397,12 +397,12 @@ that property type to not be nullable, for example.
 
 .. tip::
 
-     When used at the root of ``@OA\Response`` and ``@OA\Parameter``, ``@Model`` is automatically nested
-     in a ``@OA\Schema``.
+     When used at the root of ``#[OA\Response]`` and ``#[OA\Parameter]``, ``#[Model]`` is automatically nested
+     in a ``#[OA\Schema]``.
 
      The media type defaults to ``application/json``.
 
-     To use ``@Model`` directly within a ``@OA\Schema``, ``@OA\Items`` or ``@OA\Property``, you have to use the ``$ref`` field::
+     To use ``#[Model]`` directly within a ``#[OA\Schema]``, ``#[OA\Items]`` or ``#[OA\Property]``, you have to use the ``$ref`` field::
 
 .. configuration-block::
 
@@ -462,12 +462,12 @@ General PHP objects
 .. tip::
 
     **If you're not using the JMS Serializer**, the `Symfony PropertyInfo component`_ is used to describe your models.
-    It supports doctrine annotations, type hints, and even PHP doc blocks.
+    It supports doctrine attributes/annotations, type hints, and even PHP doc blocks.
     It does also support serialization groups when using the Symfony serializer.
 
     **If you're using the JMS Serializer**, the metadata of the JMS serializer are used by default to describe your
     models. Additional information is extracted from the PHP doc block comment,
-    but the property types must be specified in the JMS annotations.
+    but the property types must be specified in the JMS attributes/annotations.
 
     NOTE: If you are using serialization contexts (e.g. Groups) each permutation will be treated as a separate Path. For example if you have the following two variations defined in different places in your code:
 
@@ -524,14 +524,14 @@ General PHP objects
     When using the JMS serializer combined with `willdurand/Hateoas`_ (and the `BazingaHateoasBundle`_),
     HATEOAS metadata are automatically extracted
 
-If you want to customize the documentation of an object's property, you can use ``@OA\Property``::
+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 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
@@ -585,7 +585,7 @@ If you want to customize the documentation of an object's property, you can use
             }
         }
 
-See the `OpenAPI 3.0 specification`__ to see all the available fields of ``@OA\Property``.
+See the `OpenAPI 3.0 specification`__ to see all the available fields of ``#[@OA\Property]``.
 
 __ https://swagger.io/specification/
 

docs/security.rst

@@ -24,7 +24,7 @@ This will add the Bearer security policy to all registered paths.
 Overriding Specific Paths
 -------------------------
 
-The security policy can be overridden for a path using the ``Security`` annotation/attribute.
+The security policy can be overridden for a path using the ``Security`` attribute/annotation.
 
 .. configuration-block::
 
@@ -38,7 +38,7 @@ The security policy can be overridden for a path using the ``Security`` annotati
 
         #[Security(name: "ApiKeyAuth")]
 
-Notice at the bottom of the docblock is a ``Security`` annotation/attribute with a name of `ApiKeyAuth`. This will override the global security policy to only accept the ``ApiKeyAuth`` policy for this path.
+Notice at the bottom of the docblock is a ``Security`` attribute/annotation with a name of `ApiKeyAuth`. This will override the global security policy to only accept the ``ApiKeyAuth`` policy for this path.
 
 You can also completely remove security from a path by providing ``Security`` with a name of ``null``.