Merge branch 'master' into 5.x

# Conflicts:
#	tests/Functional/Configs/annotations.yaml

.gitattributes

@@ -1,6 +1,6 @@
 .* export-ignore
 *.md export-ignore
-Tests export-ignore
-Resources/doc export-ignore
+tests export-ignore
+docs export-ignore
 phpunit export-ignore
 phpunit.xml.dist export-ignore

.symfony.bundle.yaml

@@ -3,4 +3,4 @@ maintained_branches: ["3.x", "master"]
 current_branch: "master"
 dev_branch: "master"
 dev_branch_alias: "4.x"
-doc_dir: "Resources/doc/"
+doc_dir: "docs/"

CHANGELOG.md

@@ -1,6 +1,25 @@
 CHANGELOG
 =========
 
+4.22.0
+-----
+* Updated bundle directory structure to recommended file structure as described in https://symfony.com/doc/7.0/bundles/best_practices.html.
+
+  It might be necessary to reinstall the assets:
+  ```bash
+    bin/console assets:install
+  ```
+
+4.21.0
+-----
+* Added bundle configuration options `nelmio_api_doc.cache.pool` and `nelmio_api_doc.cache.item_id`.
+  ```yml
+  nelmio_api_doc:
+      cache:
+          pool: app.cache
+          item_id: nelmio_api_doc.docs
+  ```
+  
 4.20.0
 -----
 * Added Redocly as an alternative to Swagger UI. https://github.com/Redocly/redoc.

composer.json

@@ -74,15 +74,12 @@
     },
     "autoload": {
         "psr-4": {
-            "Nelmio\\ApiDocBundle\\": ""
-        },
-        "exclude-from-classmap": [
-            "Tests/"
-        ]
+            "Nelmio\\ApiDocBundle\\": "src/"
+        }
     },
     "autoload-dev": {
         "psr-4": {
-            "Nelmio\\ApiDocBundle\\Tests\\": "Tests/"
+            "Nelmio\\ApiDocBundle\\Tests\\": "tests/"
         }
     },
     "extra": {

Resources/doc/areas.rst → docs/areas.rst

@@ -1,98 +1,98 @@
-Areas
-=====
-
-We've already seen that you can configure which routes are documented using ``nelmio_api_doc.areas``:
-
-.. code-block:: yaml
-
-    nelmio_api_doc:
-        areas:
-            path_patterns: [ ^/api ]
-            host_patterns: [ ^api\. ]
-            name_patterns: [ ^api_v1 ]
-
-But in fact, this config option is way more powerful and allows you to split your documentation in several parts.
-
-Configuration
--------------
-
-You can define areas which will each generates a different documentation:
-
-.. code-block:: yaml
-
-    nelmio_api_doc:
-        areas:
-            default:
-                path_patterns: [ ^/api ]
-                host_patterns: [ ^api\. ]
-            internal:
-                path_patterns: [ ^/internal ]
-            commercial:
-                path_patterns: [ ^/commercial ]
-            store:
-                # Includes routes with names containing 'store'
-                name_patterns: [ store ]
-            
-
-Your main documentation is under the ``default`` area. It's the one shown when accessing ``/api/doc``.
-
-Then update your routing to be able to access your different documentations:
-
-.. code-block:: yaml
-
-    # app/config/routing.yaml
-    app.swagger_ui:
-        path: /api/doc/{area}
-        methods: GET
-        defaults: { _controller: nelmio_api_doc.controller.swagger_ui, area: default }
-
-    # With Redocly UI
-    # app/config/routing.yaml
-    #app.redocly:
-    #    path: /api/doc/{area}
-    #    methods: GET
-    #    defaults: { _controller: nelmio_api_doc.controller.redocly, area: default }
-
-    # To expose them as JSON
-    #app.swagger.areas:
-    #    path: /api/doc/{area}.json
-    #    methods: GET
-    #    defaults: { _controller: nelmio_api_doc.controller.swagger }
-
-
-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
---------------------------------------------------------
-
-You can use the `@Areas` annotation inside your controllers to define your routes' areas.
-
-First, you need to define which areas will use the`@Areas` annotations to filter 
-the routes that should be documented:
-
-.. code-block:: yaml
-
-    nelmio_api_doc:
-        areas:
-            default:
-                path_patterns: [ ^/api ]
-            internal:
-                with_annotation: true
-                
-Then add the annotation before your controller or action::
-
-    use Nelmio\Annotations 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()
-        {
-           ...
-        }
-    }
+Areas
+=====
+
+We've already seen that you can configure which routes are documented using ``nelmio_api_doc.areas``:
+
+.. code-block:: yaml
+
+    nelmio_api_doc:
+        areas:
+            path_patterns: [ ^/api ]
+            host_patterns: [ ^api\. ]
+            name_patterns: [ ^api_v1 ]
+
+But in fact, this config option is way more powerful and allows you to split your documentation in several parts.
+
+Configuration
+-------------
+
+You can define areas which will each generates a different documentation:
+
+.. code-block:: yaml
+
+    nelmio_api_doc:
+        areas:
+            default:
+                path_patterns: [ ^/api ]
+                host_patterns: [ ^api\. ]
+            internal:
+                path_patterns: [ ^/internal ]
+            commercial:
+                path_patterns: [ ^/commercial ]
+            store:
+                # Includes routes with names containing 'store'
+                name_patterns: [ store ]
+
+
+Your main documentation is under the ``default`` area. It's the one shown when accessing ``/api/doc``.
+
+Then update your routing to be able to access your different documentations:
+
+.. code-block:: yaml
+
+    # app/config/routing.yaml
+    app.swagger_ui:
+        path: /api/doc/{area}
+        methods: GET
+        defaults: { _controller: nelmio_api_doc.controller.swagger_ui, area: default }
+
+    # With Redocly UI
+    # app/config/routing.yaml
+    #app.redocly:
+    #    path: /api/doc/{area}
+    #    methods: GET
+    #    defaults: { _controller: nelmio_api_doc.controller.redocly, area: default }
+
+    # To expose them as JSON
+    #app.swagger.areas:
+    #    path: /api/doc/{area}.json
+    #    methods: GET
+    #    defaults: { _controller: nelmio_api_doc.controller.swagger }
+
+
+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
+--------------------------------------------------------
+
+You can use the `@Areas` annotation inside your controllers to define your routes' areas.
+
+First, you need to define which areas will use the`@Areas` annotations to filter
+the routes that should be documented:
+
+.. code-block:: yaml
+
+    nelmio_api_doc:
+        areas:
+            default:
+                path_patterns: [ ^/api ]
+            internal:
+                with_annotation: true
+
+Then add the annotation before your controller or action::
+
+    use Nelmio\Annotations 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()
+        {
+           ...
+        }
+    }