Merge pull request #726 from rahulhaque/master

Adds the ability to declare 'authenticated' in controller doc block

docs/documenting.md

@@ -94,9 +94,9 @@ They will be included in the generated documentation text and example requests.
 
 **Result:**
 
-![](body_params_1.png)
+![](./../body_params_1.png)
 
-![](body_params_2.png)
+![](./../body_params_2.png)
 
 ### Example parameters
 For each parameter in your request, this package will generate a random value to be used in the example requests. If you'd like to specify an example value, you can do so by adding `Example: your-example` to the end of your description. For instance:
@@ -114,11 +114,11 @@ For each parameter in your request, this package will generate a random value to
 
 You can also exclude a particular parameter from the generated examples (for all languages) by annotating it with `No-example`. For instance:
 ```php
-       /**
-        * @queryParam location_id required The id of the location. Example: 1
-        * @queryParam user_id required The id of the user. No-example
-        * @queryParam page required The page number. Example: 4
-        */
+    /**
+    * @queryParam location_id required The id of the location. Example: 1
+    * @queryParam user_id required The id of the user. No-example
+    * @queryParam page required The page number. Example: 4
+    */
 ```
 Outputs: 
 ```bash
@@ -151,6 +151,41 @@ public function createPost(MyRequest $request)
 ## Indicating authentication status
 You can use the `@authenticated` annotation on a method to indicate if the endpoint is authenticated. A "Requires authentication" badge will be added to that route in the generated documentation.
 
+Just like `@group` annotation, you can also specify an `@authenticated` on a single method to override the authenticated status defined at the controller level.
+
+```php
+/**
+ * @authenticated
+ *
+ * APIs for managing users
+ */
+class UserController extends Controller
+{
+
+	/**
+	 * Create a user
+	 *
+	 * [Insert optional longer description of the API endpoint here.]
+	 *
+	 */
+	 public function createUser()
+	 {
+
+	 }
+
+	/**
+	 * @group Account management
+	 *
+	 */
+	 public function changePassword()
+	 {
+
+	 }
+}
+```
+
+Now all the methods under this controller will have "Requires authentication" badge enabled.
+
 ## Providing an example response
 You can provide an example response for a route. This will be displayed in the examples section. There are several ways of doing this.
 

src/Extracting/Strategies/Metadata/GetFromDocBlocks.php

@@ -17,15 +17,16 @@ public function __invoke(Route $route, ReflectionClass $controller, ReflectionMe
         $docBlocks = RouteDocBlocker::getDocBlocksFromRoute($route);
         /** @var DocBlock $methodDocBlock */
         $methodDocBlock = $docBlocks['method'];
+        $classDocBlock = $docBlocks['class'];
 
-        list($routeGroupName, $routeGroupDescription, $routeTitle) = $this->getRouteGroupDescriptionAndTitle($methodDocBlock, $docBlocks['class']);
+        list($routeGroupName, $routeGroupDescription, $routeTitle) = $this->getRouteGroupDescriptionAndTitle($methodDocBlock, $classDocBlock);
 
         return [
             'groupName' => $routeGroupName,
             'groupDescription' => $routeGroupDescription,
             'title' => $routeTitle ?: $methodDocBlock->getShortDescription(),
             'description' => $methodDocBlock->getLongDescription()->getContents(),
-            'authenticated' => $this->getAuthStatusFromDocBlock($methodDocBlock->getTags()),
+            'authenticated' => $this->getAuthStatusFromDocBlock($classDocBlock->getTags())?:$this->getAuthStatusFromDocBlock($methodDocBlock->getTags()),
         ];
     }
 
@@ -48,7 +49,7 @@ protected function getAuthStatusFromDocBlock(array $tags)
      * @param DocBlock $methodDocBlock
      * @param DocBlock $controllerDocBlock
      *
-     * @return array The route group name, the group description, ad the route title
+     * @return array The route group name, the group description, and the route title
      */
     protected function getRouteGroupDescriptionAndTitle(DocBlock $methodDocBlock, DocBlock $controllerDocBlock)
     {