Separate endpoint group anem frmo group description and key by group name. Fixes #535

resources/views/documentarian.blade.php

@@ -5,10 +5,12 @@
 {!! $infoText !!}
 <!-- END_INFO -->
 {!! $prependMd !!}
-@foreach($parsedRoutes as $group => $routes)
-@if($group)
-#{!! $group !!}
+@foreach($parsedRoutes as $groupName => $routes)
+@if($groupName)
+#{!! $groupName !!}
 @endif
+{{-- We pick the first non-empty description we see. --}}
+{!! array_first($routes, function ($route) { return $route['groupDescription'] !== ''; })['groupDescription'] ?? '' !!}
 @foreach($routes as $parsedRoute)
 @if($writeCompareFile === true)
 {!! $parsedRoute['output'] !!}

src/Commands/GenerateDocumentation.php

@@ -82,10 +82,10 @@ class GenerateDocumentation extends Command
 
         $generator = new Generator($this->docConfig);
         $parsedRoutes = $this->processRoutes($generator, $routes);
-        $parsedRoutes = collect($parsedRoutes)->groupBy('group')
+        $parsedRoutes = collect($parsedRoutes)->groupBy('groupName')
             ->sortBy(static function ($group) {
                 /* @var $group Collection */
-                return $group->first()['group'];
+                return $group->first()['groupName'];
             }, SORT_NATURAL);
 
         $this->writeMarkdown($parsedRoutes);

src/Tools/Generator.php

@@ -57,7 +57,8 @@ class Generator
         $controller = new ReflectionClass($class);
         $method = $controller->getMethod($method);
 
-        $routeGroup = $this->getRouteGroup($controller, $method);
+        list($routeGroupName, $routeGroupDescription) = $this->getRouteGroup($controller, $method);
+
         $docBlock = $this->parseDocBlock($method);
         $bodyParameters = $this->getBodyParameters($method, $docBlock['tags']);
         $queryParameters = $this->getQueryParameters($method, $docBlock['tags']);
@@ -69,7 +70,8 @@ class Generator
 
         $parsedRoute = [
             'id' => md5($this->getUri($route).':'.implode($this->getMethods($route))),
-            'group' => $routeGroup,
+            'groupName' => $routeGroupName,
+            'groupDescription' => $routeGroupDescription,
             'title' => $docBlock['short'],
             'description' => $docBlock['long'],
             'methods' => $this->getMethods($route),
@@ -271,7 +273,7 @@ class Generator
      * @param ReflectionClass $controller
      * @param ReflectionMethod $method
      *
-     * @return string
+     * @return array The route group name and description
      */
     protected function getRouteGroup(ReflectionClass $controller, ReflectionMethod $method)
     {
@@ -281,7 +283,11 @@ class Generator
             $phpdoc = new DocBlock($docBlockComment);
             foreach ($phpdoc->getTags() as $tag) {
                 if ($tag->getName() === 'group') {
-                    return $tag->getContent();
+                    $routeGroup = trim($tag->getContent());
+                    $routeGroupParts = explode("\n", $tag->getContent());
+                    $routeGroupName = array_shift($routeGroupParts);
+                    $routeGroupDescription = implode("\n", $routeGroupParts);
+                    return [$routeGroupName, $routeGroupDescription];
                 }
             }
         }
@@ -291,12 +297,15 @@ class Generator
             $phpdoc = new DocBlock($docBlockComment);
             foreach ($phpdoc->getTags() as $tag) {
                 if ($tag->getName() === 'group') {
-                    return $tag->getContent();
+                    $routeGroupParts = explode("\n", $tag->getContent());
+                    $routeGroupName = array_shift($routeGroupParts);
+                    $routeGroupDescription = implode("\n", $routeGroupParts);
+                    return [$routeGroupName, $routeGroupDescription];
                 }
             }
         }
 
-        return $this->config->get(('default_group'));
+        return [$this->config->get(('default_group')), ''];
     }
 
     private function normalizeParameterType($type)

tests/Fixtures/TestGroupController.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Mpociot\ApiDoc\Tests\Fixtures;
+
+/**
+ * @group 1. Group 1
+ *
+ * Group 1 APIs
+ */
+class TestGroupController
+{
+
+    /**
+     * Some endpoint.
+     *
+     * By default, this is in Group 1.
+     */
+    public function action1()
+    {
+    }
+
+    /**
+     * Another endpoint
+     *
+     * Here we specify a group. This is also in Group 1.
+     *
+     * @group 1. Group 1
+     */
+    public function action1b()
+    {
+    }
+
+    /**
+     * @group 2. Group 2
+     */
+    public function action2()
+    {
+    }
+
+    /** @group 10. Group 10 */
+    public function action10()
+    {
+    }
+}

tests/Fixtures/TestNaturalSortController.php

@@ -1,21 +0,0 @@
-<?php
-
-namespace Mpociot\ApiDoc\Tests\Fixtures;
-
-class TestNaturalSortController
-{
-    /** @group 1. Group 1 */
-    public function action1()
-    {
-    }
-
-    /** @group 2. Group 2 */
-    public function action2()
-    {
-    }
-
-    /** @group 10. Group 10 */
-    public function action10()
-    {
-    }
-}

tests/Fixtures/index.md

@@ -21,6 +21,8 @@ Welcome to the generated API reference.
 <!-- END_INFO -->
 
 #Group A
+
+
 <!-- START_264ee15c728df32e7ca6eedce5e42dcb -->
 ## Example title.
 

tests/Fixtures/partial_resource_index.md

@@ -21,6 +21,8 @@ Welcome to the generated API reference.
 <!-- END_INFO -->
 
 #general
+
+
 <!-- START_fc1e4f6a697e3c48257de845299b71d5 -->
 ## Display a listing of the resource.
 

tests/Fixtures/resource_index.md

@@ -21,6 +21,8 @@ Welcome to the generated API reference.
 <!-- END_INFO -->
 
 #general
+
+
 <!-- START_fc1e4f6a697e3c48257de845299b71d5 -->
 ## Display a listing of the resource.
 

tests/Unit/GeneratorTestCase.php

@@ -214,7 +214,7 @@ abstract class GeneratorTestCase extends TestCase
     public function can_parse_route_group()
     {
         $route = $this->createRoute('GET', '/api/test', 'dummy');
-        $routeGroup = $this->generator->processRoute($route)['group'];
+        $routeGroup = $this->generator->processRoute($route)['groupName'];
 
         $this->assertSame('Group A', $routeGroup);
     }
@@ -223,7 +223,7 @@ abstract class GeneratorTestCase extends TestCase
     public function method_can_override_controller_group()
     {
         $route = $this->createRoute('GET', '/api/test', 'withGroupOverride');
-        $routeGroup = $this->generator->processRoute($route)['group'];
+        $routeGroup = $this->generator->processRoute($route)['groupName'];
 
         $this->assertSame('Group B', $routeGroup);
     }