ability to add descriptions

Author: mtrajano

README.md

@@ -1,6 +1,6 @@
 # Laravel Swagger
 
-This package scans your laravel project's routes and auto generates a Swagger 2.0 documentation for you. If you inject Form Request classes in your controller's actions as request validation, it will also generate the parameters for each request that has them. It will take into account wether the request is a GET/HEAD/DELETE or a POST/PUT/PATCH request and make its best guess as to the type of parameter object it should generate. It will also generate the path parameters if you route contains them.
+This package scans your laravel project's routes and auto generates a Swagger 2.0 documentation for you. If you inject Form Request classes in your controller's actions as request validation, it will also generate the parameters for each request that has them. It will take into account wether the request is a GET/HEAD/DELETE or a POST/PUT/PATCH request and make its best guess as to the type of parameter object it should generate. It will also generate the path parameters if you route contains them. Finally, this package will also scan any documentation you have in your action methods and add it as description to that path, along with any appropriate annotations such as @deprecated.
 
 ## Installation
 
@@ -30,6 +30,11 @@ Say you have a route `/api/users/{id}` that maps to `UserController@show`
 
 Your sample controller might look like this:
 ```php
+/**
+ * Return all the details of a user
+ *
+ * @deprecated
+ */
 class UserController extends Controller
 {
     public function show(UserShowRequest $request, $id)
@@ -68,7 +73,9 @@ Running `php artisan laravel-swagger:generate > swagger.json` will generate the
     "paths": {
         "\/api\/user\/{id}": {
             "get": {
-                "description": "GET \/api\/user\/{id}",
+                "summary": "GET \/api\/user\/{id}",
+                "description": "Return all the details of a user",
+                "deprecated": true
                 "responses": {
                     "200": {
                         "description": "OK"

config/laravel-swagger.php

@@ -47,4 +47,16 @@
     'ignoredMethods' => [
         'head',
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Include descriptions
+    |--------------------------------------------------------------------------
+    |
+    | If true will parse the action method docBlock for any lines that are not
+    | part of an annotation and will add it as the route's description
+    |
+    */
+
+    'parseDescriptions' => true,
 ];

src/Generator.php

@@ -108,10 +108,16 @@ protected function getRouteUri(Route $route)
 
     protected function generatePath()
     {
-        $methodDescription = strtoupper($this->method);
+        $requestMethod = strtoupper($this->method);
+        $actionInstance = $this->action ? $this->getActionClassInstance($this->action) : null;
+        $docBlock = $actionInstance ? ($actionInstance->getDocComment() ?: "") : "";
+
+        list($isDeprecated, $description) = $this->parseActionDocBlock($docBlock);
 
         $this->docs['paths'][$this->uri][$this->method] = [
-            'description' => "$methodDescription {$this->uri}",
+            'summary' => "$requestMethod {$this->uri}",
+            'description' => $description,
+            'deprecated' => $isDeprecated,
             'responses' => [
                 '200' => [
                     'description' => 'OK'
@@ -143,9 +149,7 @@ protected function getFormRules()
     {
         if (!is_string($this->action)) return false;
 
-        $parsedAction = Str::parseCallback($this->action);
-
-        $parameters = (new ReflectionMethod($parsedAction[0], $parsedAction[1]))->getParameters();
+        $parameters = $this->getActionClassInstance($this->action)->getParameters();
 
         foreach ($parameters as $parameter) {
             $class = (string) $parameter->getType();
@@ -167,4 +171,82 @@ protected function getParameterGenerator($rules)
                 return new Parameters\QueryParameterGenerator($rules);
         }
     }
+
+    private function getActionClassInstance(string $action)
+    {
+        list($class, $method) = Str::parseCallback($action);
+
+        return new ReflectionMethod($class, $method);
+    }
+
+    private function parseActionDocBlock(string $docBlock)
+    {
+        $isDeprecated = !!preg_match('/@deprecated/', $docBlock);
+
+        preg_match('/\/\*\s*(.+?)\s*\*\//sm', $docBlock, $matches);
+        $commentWithoutTrailingCharacters = isset($matches[1]) ? $matches[1] : "";
+
+        if (!$this->config['parseDescriptions']) {
+            $commentWithoutTrailingCharacters = "";
+        }
+
+        if (empty($commentWithoutTrailingCharacters)) {
+            return [$isDeprecated, $commentWithoutTrailingCharacters];
+        }
+
+        $lines = explode("\n", $commentWithoutTrailingCharacters);
+        $lines = array_map('trim', $lines);
+
+        $description = $this->buildDescription($lines);
+
+        return [$isDeprecated, $description];
+    }
+
+    private function buildDescription(array $matches)
+    {
+        $commentLines = $this->getNonAnnotationLines($matches);
+        $commentLines = $this->trimLines($commentLines);
+        $commentLines = $this->trimAroundComment($commentLines);
+
+        return implode("\n", $commentLines);
+    }
+
+    private function getNonAnnotationLines(array $lines)
+    {
+        return array_filter($lines, function($line) {
+            return !preg_match('/^\*+\s*@/', $line);
+        });
+    }
+
+    private function trimLines(array $comments)
+    {
+        $comments = array_map(function($line) {
+            preg_match('/^\**(.*)/', $line, $matches);
+
+            return isset($matches[1]) ? $matches[1] : "\n";
+        }, $comments);
+
+        return array_map('trim', $comments);
+    }
+
+    private function trimAroundComment(array $lines)
+    {
+        foreach ($lines as $key => $value) {
+            if (trim($value)) {
+                break;
+            }
+
+            unset($lines[$key]);
+        }
+
+        foreach (array_reverse($lines, true) as $key => $value) {
+            if (trim($value)) {
+                break;
+            }
+
+            unset($lines[$key]);
+        }
+
+        return array_values($lines);
+    }
 }

tests/GeneratorTest.php

@@ -43,6 +43,7 @@ public function testHasPaths($docs)
         $this->assertEquals([
             '/users',
             '/users/{id}',
+            '/users/details',
             '/api',
             '/api/store',
         ], array_keys($docs['paths']));
@@ -53,19 +54,51 @@ public function testHasPaths($docs)
     /**
      * @depends testHasPaths
      */
-    public function testPathData($paths)
+    public function testPathMethods($paths)
     {
         $this->assertArrayHasKey('get', $paths['/users']);
         $this->assertArrayNotHasKey('head', $paths['/users']);
         $this->assertArrayHasKey('post', $paths['/users']);
 
+        $this->assertArrayHasKey('get', $paths['/users/{id}']);
+
+        $this->assertArrayHasKey('get', $paths['/users/details']);
+    }
+
+    /**
+     * @depends testHasPaths
+     */
+    public function testRouteData($paths)
+    {
+
+        $expectedPostDescription = <<<EOD
+Store a new user in the application
+Data is validated [see description here](https://example.com) so no bad data can be passed.
+
+Please read the documentation for more information
+EOD;
+
+        $this->assertArrayHasKey('summary', $paths['/users']['get']);
         $this->assertArrayHasKey('description', $paths['/users']['get']);
         $this->assertArrayHasKey('responses', $paths['/users']['get']);
+        $this->assertArrayHasKey('deprecated', $paths['/users']['get']);
         $this->assertArrayNotHasKey('parameters', $paths['/users']['get']);
 
-        $this->assertArrayHasKey('description', $paths['/users']['post']);
-        $this->assertArrayHasKey('responses', $paths['/users']['post']);
-        $this->assertArrayHasKey('parameters', $paths['/users']['post']);
+        $this->assertEquals('GET /users', $paths['/users']['get']['summary']);
+        $this->assertEquals(false, $paths['/users']['get']['deprecated']);
+        $this->assertEquals('Get a list of of users in the application', $paths['/users']['get']['description']);
+
+        $this->assertEquals('POST /users', $paths['/users']['post']['summary']);
+        $this->assertEquals(true, $paths['/users']['post']['deprecated']);
+        $this->assertEquals($expectedPostDescription, $paths['/users']['post']['description']);
+
+        $this->assertEquals('GET /users/{id}', $paths['/users/{id}']['get']['summary']);
+        $this->assertEquals(false, $paths['/users/{id}']['get']['deprecated']);
+        $this->assertEquals("", $paths['/users/{id}']['get']['description']);
+
+        $this->assertEquals('GET /users/details', $paths['/users/details']['get']['summary']);
+        $this->assertEquals(true, $paths['/users/details']['get']['deprecated']);
+        $this->assertEquals("", $paths['/users/details']['get']['description']);
     }
 
     public function testOverwriteIgnoreMethods()
@@ -77,6 +110,15 @@ public function testOverwriteIgnoreMethods()
         $this->assertArrayHasKey('head', $docs['paths']['/users']);
     }
 
+    public function testParseDescriptionFalse()
+    {
+        $this->config['parseDescriptions'] = false;
+
+        $docs = (new Generator($this->config))->generate();
+
+        $this->assertEquals("", $docs['paths']['/users']['post']['description']);
+    }
+
     public function testOptionalData()
     {
         $optionalData = [
@@ -111,7 +153,7 @@ public function testOptionalData()
     /**
      * @param string|null $routeFilter
      * @param array $expectedRoutes
-     * 
+     *
      * @dataProvider filtersRoutesProvider
      */
     public function testFiltersRoutes($routeFilter, $expectedRoutes)
@@ -132,7 +174,7 @@ public function testFiltersRoutes($routeFilter, $expectedRoutes)
     public function filtersRoutesProvider()
     {
         return [
-            'No Filter' => [null, ['/users', '/users/{id}', '/api', '/api/store']],
+            'No Filter' => [null, ['/users', '/users/{id}', '/users/details', '/api', '/api/store']],
             '/api Filter' => ['/api', ['/api', '/api/store']],
             '/=nonexistant Filter' => ['/nonexistant', []],
         ];

tests/Stubs/Controllers/UserController.php

@@ -8,6 +8,7 @@
 
 class UserController extends Controller
 {
+    /** Get a list of of users in the application */
     public function index()
     {
         return json_encode([['first_name' => 'John'], ['first_name' => 'Jack']]);
@@ -18,8 +19,25 @@ public function show(UserShowRequest $request, $id)
         return json_encode(['first_name' => 'John']);
     }
 
+    /**
+     * Store a new user in the application
+     * Data is validated [see description here](https://example.com) so no bad data can be passed.
+     *
+     * Please read the documentation for more information
+     *
+     * @param UserStoreRequest $request
+     * @deprecated
+     */
     public function store(UserStoreRequest $request)
     {
         return json_encode($request->all());
     }
+
+    /**
+     * @deprecated
+     */
+    public function details()
+    {
+        return json_encode([]);
+    }
 }

tests/TestCase.php

@@ -16,6 +16,7 @@ protected function getEnvironmentSetUp($app)
         $app['router']->get('/users', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@index');
         $app['router']->get('/users/{id}', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@show');
         $app['router']->post('/users', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@store');
+        $app['router']->get('/users/details', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@details');
         $app['router']->get('/api', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\ApiController@index');
         $app['router']->put('/api/store', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\ApiController@store');
     }