Merge pull request #1954 from jackcutting/allow-complete-override-of-security

Allow global security policies to be removed

Describer/OpenApiPhpDescriber.php

@@ -109,6 +109,13 @@ final class OpenApiPhpDescriber
 
                 if ($annotation instanceof Security) {
                     $annotation->validate();
+
+                    if (null === $annotation->name) {
+                        $mergeProperties->security = [];
+
+                        continue;
+                    }
+
                     $mergeProperties->security[] = [$annotation->name => $annotation->scopes];
 
                     continue;

Resources/doc/index.rst

@@ -341,6 +341,7 @@ If you need more complex features, take a look at:
     customization
     commands
     faq
+    security
 
 .. _`Symfony PropertyInfo component`: https://symfony.com/doc/current/components/property_info.html
 .. _`willdurand/Hateoas`: https://github.com/willdurand/Hateoas

Resources/doc/security.rst

@@ -0,0 +1,43 @@
+Security
+========
+
+A default security policy can be added in ``nelmio_api_doc.documentation.security``
+
+.. code-block:: yaml
+
+    nelmio_api_doc:
+        documentation:
+            components:
+            securitySchemes:
+                Bearer:
+                    type: http
+                    scheme: bearer
+                ApiKeyAuth:
+                    type: apiKey
+                    in: header
+                    name: X-API-Key
+            security:
+                Bearer: []
+
+This will add the Bearer security policy to all registered paths.
+
+Overriding Specific Paths
+-------------------------
+
+The security policy can be overriden for a path using the ``@Security`` annotation.
+
+.. code-block:: php
+
+    /**
+     * @Security(name="ApiKeyAuth")
+     */
+
+Notice at the bottom of the docblock is a ``@Security`` 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``.
+
+.. code-block:: php
+
+    /**
+     * @Security(name=null)
+     */

Tests/Functional/Controller/ApiController80.php

@@ -164,6 +164,16 @@ class ApiController80
     {
     }
 
+    /**
+     * @Route("/securityOverride")
+     * @OA\Response(response="201", description="")
+     * @Security(name="api_key")
+     * @Security(name=null)
+     */
+    public function securityActionOverride()
+    {
+    }
+
     /**
      * @Route("/swagger/symfonyConstraints", methods={"GET"})
      * @OA\Response(

Tests/Functional/Controller/ApiController81.php

@@ -50,4 +50,12 @@ class ApiController81 extends ApiController80
     public function securityActionAttributes()
     {
     }
+
+    #[Route('/security_override_attributes')]
+    #[OA\Response(response: '201', description: '')]
+    #[Security(name: 'api_key')]
+    #[Security(name: null)]
+    public function securityOverrideActionAttributes()
+    {
+    }
 }

Tests/Functional/FunctionalTest.php

@@ -369,6 +369,24 @@ class FunctionalTest extends WebTestCase
         }
     }
 
+    /**
+     * @dataProvider provideSecurityOverrideRoute
+     */
+    public function testSecurityOverrideAction(string $route)
+    {
+        $operation = $this->getOperation($route, 'get');
+        $this->assertEquals([], $operation->security);
+    }
+
+    public function provideSecurityOverrideRoute(): iterable
+    {
+        yield 'Annotations' => ['/api/securityOverride'];
+
+        if (\PHP_VERSION_ID >= 80100) {
+            yield 'Attributes' => ['/api/security_override_attributes'];
+        }
+    }
+
     public function testClassSecurityAction()
     {
         $operation = $this->getOperation('/api/security/class', 'get');