feat: [5.x] attribute consistency

.symfony.bundle.yaml

@@ -1,6 +1,5 @@
-branches: ["2.x", "3.x", "master"]
-maintained_branches: ["3.x", "master"]
-current_branch: "master"
-dev_branch: "master"
-dev_branch_alias: "4.x"
-doc_dir: { "3.x": "Resources/doc/", "master": "docs/" }
+branches: ["2.x", "3.x", "master", "5.x"]
+maintained_branches: ["master", "5.x"]
+current_branch: "5.x"
+dev_branch: "5.x"
+doc_dir: { "3.x": "Resources/doc/", "master": "docs/", "5.x": "docs/" }

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`.

UPGRADE-3.0.md

@@ -17,7 +17,7 @@ First, copy this command in ``src/AppBundle/Command/SwaggerDocblockConvertComman
 // src/AppBundle/Command/SwaggerDocblockConvertCommand.php
 namespace AppBundle\Command;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;

UPGRADE-5.0.md

@@ -25,3 +25,15 @@ This causes the following breaking changes in classes that used annotations:
 - BC BREAK: Removed 2nd parameter `?Reader $annotationReader` from `Nelmio\ApiDocBundle\ModelDescriber\ObjectModelDescriber::__construct()`
 - BC BREAK: Removed 1st parameter `?Reader $annotationReader` from `Nelmio\ApiDocBundle\RouteDescriber\FosRestDescriber::__construct()`
 - BC BREAK: Removed 1st parameter `?Reader $annotationReader` from `Nelmio\ApiDocBundle\Routing\FilteredRouteCollectionBuilder::__construct()`
+
+## BC BREAK: `Nelmio\ApiDocBundle\Annotation` namespace has been remove in favor of `Nelmio\ApiDocBundle\Attribute`
+
+## BC BREAK: Configuration option `with_annotation` has been renamed to `with_attribute`
+```diff
+nelmio_api_doc:
+    areas:
+        path_patterns:
+            - ^/api/foo
+-       with_annotation: true
++       with_attribute: true
+```

composer.json

@@ -92,7 +92,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "4.x-dev"
+            "dev-master": "4.x-dev",
+            "dev-5.x": "5.x-dev"
         }
     },
     "scripts-descriptions": {

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,14 @@ 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-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
@@ -77,22 +77,29 @@ the routes that should be documented:
             default:
                 path_patterns: [ ^/api ]
             internal:
-                with_annotation: true
+                with_attribute: true
 
-Then add the annotation before your controller or action::
+Then add the attribute before your controller or action::
 
-    use Nelmio\Annotations as Nelmio;
+.. configuration-block::
+
+    .. 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,21 @@ 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-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 +216,22 @@ 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 with a ``type`` or ``ref``.
 Note, however, that a ``type="object"`` will still read all a models properties.
 
-.. code-block:: php
+.. configuration-block::
 
-    <?php
-    use OpenApi\Annotations as OA;
-    use Nelmio\ApiDocBundle\Annotation\Model;
+    .. code-block:: php-attributes
 
-    /**
-     * @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
-    {
-        // ...
-    }
+        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
+        {
+            // ...
+        }