Merge branch 'master' into enum-handling-fix

nelmio · Oct 31, 2024 · 632d3be · 632d3be
2 parents a2b6874 + 3a58743
commit 632d3be
Show file tree

Hide file tree

Showing 52 changed files with 801 additions and 7,621 deletions.
diff --git a/.github/workflows/common/composer-install/action.yaml b/.github/workflows/common/composer-install/action.yaml
@@ -41,6 +41,6 @@ runs:
 
     - name: Install dependencies with Composer
       env:
-        SYMFONY_REQUIRE: ${{ inputs.symfony-version }}
+        SYMFONY_REQUIRE: "${{ inputs.symfony-version }}.*"
       run: composer update --no-interaction --no-progress ${{ inputs.composer-flags }}
       shell: bash
diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
@@ -26,45 +26,46 @@ jobs:
       matrix:
         include:
           - php-version: 7.4
+            symfony-require: "5.4"
             composer-flags: "--prefer-lowest"
             doctrine-annotations: true
           - php-version: 7.4
-            symfony-require: "5.4.*"
+            symfony-require: "5.4"
             doctrine-annotations: true
           - php-version: 8.0
-            symfony-require: "5.4.*"
+            symfony-require: "5.4"
             doctrine-annotations: true
           - php-version: 8.1
-            symfony-require: "5.4.*"
+            symfony-require: "5.4"
             doctrine-annotations: true
           - php-version: 8.3
-            symfony-require: "5.4.*"
+            symfony-require: "5.4"
             doctrine-annotations: true
           - php-version: 8.1
-            symfony-require: "6.4.*"
+            symfony-require: "6.4"
             doctrine-annotations: true
           - php-version: 8.3
-            symfony-require: "6.4.*"
+            symfony-require: "6.4"
             doctrine-annotations: true
           - php-version: 8.2
-            symfony-require: "7.0.*"
+            symfony-require: "7.0"
             doctrine-annotations: false
           - php-version: 8.3
-            symfony-require: "7.0.*"
+            symfony-require: "7.0"
             doctrine-annotations: false
           - php-version: 8.2
-            symfony-require: "7.1.*"
+            symfony-require: "7.1"
             doctrine-annotations: false
           - php-version: 8.3
-            symfony-require: "7.1.*"
+            symfony-require: "7.1"
             doctrine-annotations: false
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 2
 
-      - name: Install PHP without coverage
+      - name: Install PHP with coverage
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
@@ -79,7 +80,50 @@ jobs:
           composer-flags: ${{ matrix.composer-flags }}
 
       - name: PHPUnit Tests
-        run: vendor/bin/phpunit --configuration phpunit.xml.dist --coverage-text
+        run: | 
+          vendor/bin/phpunit \
+          --configuration phpunit.xml.dist \
+          --log-junit=junit-${{ matrix.php-version }}-${{ matrix.symfony-require }}-${{ matrix.doctrine-annotations }}${{ matrix.composer-flags }}.xml \
+          --coverage-clover=coverage-${{ matrix.php-version }}-${{ matrix.symfony-require }}-${{ matrix.doctrine-annotations }}${{ matrix.composer-flags }}.xml \
+          --coverage-filter=src/
+
+      - uses: actions/upload-artifact@v4
+        if: ${{ matrix.php-version != '7.4' }}
+        with:
+          name: phpunit-${{ matrix.php-version }}-${{ matrix.symfony-require }}-${{ matrix.doctrine-annotations }}${{ matrix.composer-flags }}
+          path: |
+            coverage*.xml
+            junit*.xml
+          if-no-files-found: error
+          retention-days: 2
+
+  codecov:
+    name: Codecov
+    runs-on: ubuntu-22.04
+
+    needs: phpunit
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+
+      - name: Upload test results to Codecov.io
+        uses: codecov/test-results-action@v1
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload code coverage to Codecov.io
+        uses: codecov/codecov-action@v4
+        with:
+          fail_ci_if_error: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   php-cs-fixer:
     name: PHP-CS-Fixer
@@ -96,7 +140,7 @@ jobs:
         with:
           php-version: 8.3
           tools: composer, flex
-          coverage: pcov
+          coverage: none
 
       - name: Setup dependencies
         uses: ./.github/workflows/common/composer-install
@@ -122,7 +166,7 @@ jobs:
         with:
           php-version: 8.3
           tools: composer, flex
-          coverage: pcov
+          coverage: none
 
       - name: Setup dependencies
         uses: ./.github/workflows/common/composer-install

diff --git a/CHANGELOG.md b/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`.
@@ -15,6 +31,11 @@
 ## 4.30.0
 * Create top level OpenApi Tag from Tags top level annotations/attributes
 
+## 4.25.3
+
+* Calling `DocumentationExtension::getExtendedType()` has been deprecated in favor of `DocumentationExtension::getExtendedTypes()` to align with the deprecation introduced with `symfony/symfony` version `4.2`.
+
+
 ## 4.26.0
 
 * Add ability to configure UI through configuration
@@ -149,6 +170,11 @@ doc-api:
 * Added Redocly as an alternative to Swagger UI. https://github.com/Redocly/redoc.
 * Added support for describing dictionary types in OpenAPI 3.0.
 
+## 4.17.0
+
+* Passing groups to `PropertyDescriberInterface::describe()` via the `$groups` parameter is deprecated, the parameter will get removed in a future version. Pass groups via `$context['groups']` instead.
+
+
 ## 4.0.0
 
 * Added support of OpenAPI 3.0. The internals were completely reworked and this version introduces BC breaks.
@@ -175,7 +201,7 @@ doc-api:
 
 * Add a documentation form extension. Use the ``documentation`` option to define how a form field is documented.
 * Allow references to config definitions in controllers.
-* Using `@Model` implicitely in `@SWG\Schema`, `@SWG\Items` and `@SWG\Property` is deprecated. Use `ref=@Model()` instead.
+* Using `@Model` implicitly in `@SWG\Schema`, `@SWG\Items` and `@SWG\Property` is deprecated. Use `ref=@Model()` instead.
 
   Before:
   ```php

diff --git a/config/services.xml b/config/services.xml
@@ -139,10 +139,6 @@
             <tag name="nelmio_api_doc.object_model.property_describer" />
         </service>
 
-        <service id="nelmio_api_doc.object_model.property_describers.required" class="Nelmio\ApiDocBundle\PropertyDescriber\RequiredPropertyDescriber" public="false">
-            <tag name="nelmio_api_doc.object_model.property_describer" />
-        </service>
-
         <service id="nelmio_api_doc.object_model.property_describers.object" class="Nelmio\ApiDocBundle\PropertyDescriber\ObjectPropertyDescriber" public="false">
             <tag name="nelmio_api_doc.object_model.property_describer" priority="-1000" />
         </service>

diff --git a/docs/alternative_names.rst b/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()
+                {
+                }
+            }
diff --git a/docs/areas.rst b/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()
+            {
+               ...
+            }
         }
-    }
+