authenticationRoles can be set to appear in the tooltip of the key icon for API calls that require authentication.

Annotation/ApiDoc.php

@@ -110,6 +110,11 @@ class ApiDoc
      */
     private $authentication = false;
 
+    /**
+     * @var array
+     */
+    private $authenticationRoles = array();
+
     /**
      * @var int
      */
@@ -162,6 +167,12 @@ class ApiDoc
             $this->setAuthentication((bool) $data['authentication']);
         }
 
+        if (isset($data['authenticationRoles'])) {
+            foreach ($data['authenticationRoles'] as $key => $role) {
+                $this->authenticationRoles[] = $role;
+            }
+        }
+
         if (isset($data['cache'])) {
             $this->setCache($data['cache']);
         }
@@ -374,6 +385,22 @@ class ApiDoc
         $this->authentication = $authentication;
     }
 
+    /**
+     * @return array
+     */
+    public function getAuthenticationRoles()
+    {
+        return $this->authenticationRoles;
+    }
+
+    /**
+     * @param array $authenticationRoles
+     */
+    public function setAuthenticationRoles($authenticationRoles)
+    {
+        $this->authenticationRoles = $authenticationRoles;
+    }
+
     /**
      * @return int
      */
@@ -475,6 +502,7 @@ class ApiDoc
 
         $data['https'] = $this->https;
         $data['authentication'] = $this->authentication;
+        $data['authenticationRoles'] = $this->authenticationRoles;
         $data['deprecated'] = $this->deprecated;
 
         return $data;

Extractor/Handler/JmsSecurityExtraHandler.php

@@ -22,8 +22,11 @@ class JmsSecurityExtraHandler implements HandlerInterface
     public function handle(ApiDoc $annotation, array $annotations, Route $route, \ReflectionMethod $method)
     {
         foreach ($annotations as $annot) {
-            if ($annot instanceof Secure || $annot instanceof PreAuthorize) {
+            if ($annot instanceof PreAuthorize) {
                 $annotation->setAuthentication(true);
+            } else if ($annot instanceof Secure) {
+                $annotation->setAuthentication(true);
+                $annotation->setAuthenticationRoles(is_array($annot->roles) ? $annot->roles : explode(',', $annot->roles));
             }
         }
     }

README.md

@@ -175,7 +175,7 @@ Also bundle will get information from the other annotations:
 
 * @FOS\RestBundle\Controller\Annotations\QueryParam - use as `requirements` (when strict parameter is true), `filters` (when strict is false)
 
-* @JMS\SecurityExtraBundle\Annotation\Secure - set `authentification` to true
+* @JMS\SecurityExtraBundle\Annotation\Secure - set `authentification` to true, `authenticationRoles` to the given roles
 
 * @Sensio\Bundle\FrameworkExtraBundle\Configuration\Cache - set `cache`
 

Resources/views/method.html.twig

@@ -15,7 +15,7 @@
             <span class="icon lock" title="HTTPS"></span>
         {% endif %}
         {% if data.authentication %}
-            <span class="icon keys" title="Needs authentication"></span>
+            <span class="icon keys" title="Needs {{ data.authenticationRoles|length > 0 ? data.authenticationRoles|join(', ') : 'authentication' }}"></span>
         {% endif %}
 
         <span class="path">

Tests/Annotation/ApiDocTest.php

@@ -30,6 +30,7 @@ class ApiDocTest extends TestCase
         $this->assertFalse(isset($array['description']));
         $this->assertNull($annot->getInput());
         $this->assertFalse($array['authentication']);
+        $this->assertTrue(is_array($array['authenticationRoles']));
     }
 
     public function testConstructWithInvalidData()

Tests/Extractor/ApiDocExtractorTest.php

@@ -181,6 +181,9 @@ class ApiDocExtractorTest extends WebTestCase
         $this->assertTrue(
             $annotation->getAuthentication()
         );
+        $this->assertTrue(in_array('ROLE_USER', $annotation->getAuthenticationRoles()));
+        $this->assertTrue(in_array('ROLE_FOOBAR', $annotation->getAuthenticationRoles()));
+        $this->assertEquals(2, count($annotation->getAuthenticationRoles()));
     }
 
     public function testGetWithCache()

Tests/Fixtures/Controller/TestController.php

@@ -158,7 +158,8 @@ class TestController
 
     /**
      * @ApiDoc(
-     *  authentication=true
+     *  authentication=true,
+     *  authenticationRoles={"ROLE_USER","ROLE_FOOBAR"}
      * )
      */
     public function authenticatedAction()

Tests/Formatter/SimpleFormatterTest.php

@@ -60,6 +60,7 @@ class SimpleFormatterTest extends WebTestCase
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 1 =>
@@ -94,6 +95,7 @@ class SimpleFormatterTest extends WebTestCase
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 2 =>
@@ -137,6 +139,7 @@ class SimpleFormatterTest extends WebTestCase
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 3 =>
@@ -180,6 +183,7 @@ class SimpleFormatterTest extends WebTestCase
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
             ),
@@ -202,6 +206,7 @@ class SimpleFormatterTest extends WebTestCase
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 1 =>
@@ -211,6 +216,7 @@ class SimpleFormatterTest extends WebTestCase
                     'description' => 'Action without HTTP verb',
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 2 =>
@@ -229,6 +235,7 @@ class SimpleFormatterTest extends WebTestCase
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 3 =>
@@ -237,6 +244,7 @@ class SimpleFormatterTest extends WebTestCase
                     'uri' => '/authenticated',
                     'https' => false,
                     'authentication' => true,
+                    'authenticationRoles' => array('ROLE_USER','ROLE_FOOBAR'),
                     'deprecated' => false,
                 ),
                 4 =>
@@ -437,6 +445,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 5 =>
@@ -456,6 +465,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 6 =>
@@ -496,6 +506,7 @@ And, it supports multilines until the first \'@\' char.',
                     'description' => 'This method is useful to test if the getDocComment works.',
                     'documentation' => "This method is useful to test if the getDocComment works.\nAnd, it supports multilines until the first '@' char.",
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 7 =>
@@ -504,6 +515,7 @@ And, it supports multilines until the first \'@\' char.',
                     'uri' => '/return-nested-output',
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                     'response' =>
                     array (
@@ -712,6 +724,7 @@ With multiple lines.',
                     ),
                     'https' => true,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 9 =>
@@ -729,6 +742,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 10 =>
@@ -737,6 +751,7 @@ With multiple lines.',
                     'uri' => '/z-action-with-deprecated-indicator',
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => true,
                 ),
                 11 =>
@@ -754,6 +769,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 12 =>
@@ -770,6 +786,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 13 =>
@@ -787,6 +804,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
                 14 =>
@@ -805,6 +823,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
             ),
@@ -826,6 +845,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
             ),
@@ -847,6 +867,7 @@ With multiple lines.',
                     ),
                     'https' => false,
                     'authentication' => false,
+                    'authenticationRoles' => array(),
                     'deprecated' => false,
                 ),
             ),
@@ -884,7 +905,8 @@ With multiple lines.',
             ),
             'https' => false,
             'authentication' => false,
-                    'deprecated' => false,
+            'authenticationRoles' => array(),
+            'deprecated' => false,
         );
 
         $this->assertEquals($expected, $result);