Fix #121 Implement group

Author: kitloong

config/request-docs.php

@@ -37,6 +37,15 @@
     // Can be overridden as // @LRDResponses 200|400|401
     'default_responses' => [ "200", "400", "401", "403", "404", "405", "422", "429", "500", "503"],
 
+    // By default, LRD group your routes by the first /path.
+    // This is a set of regex to group your routes by prefix.
+    'group_by' => [
+        'uri_patterns' => [
+            '^api/v[\d]+/', // `/api/v1/users/store` group as `/api/v1/users`.
+            '^api/',        // `/api/users/store` group as `/api/users`.
+        ]
+    ],
+
     // No need to touch below
     // open api config
     // used to generate open api json

src/LaravelRequestDocs.php

@@ -2,6 +2,7 @@
 
 namespace Rakutentech\LaravelRequestDocs;
 
+use Illuminate\Support\Collection;
 use Route;
 use ReflectionMethod;
 use ReflectionClass;
@@ -118,11 +119,15 @@ public function filterByMethods($docs, $get, $post, $put, $path, $delete, $head)
 
     public function groupDocs($docs, $group = 'default')
     {
-        if ($group == 'default') {
-            return $docs;
+        if ($group === 'api_uri') {
+            return $this->groupDocsByAPIURI($docs);
+        }
+
+        if ($group === 'controller_full_path') {
+            return $this->groupDocsByFQController($docs);
         }
-        $grouped = [];//unimplemented
-        return $docs;  //unimplemented, returning as it is
+
+        return $docs;
     }
 
     public function getControllersInfo(): array
@@ -363,4 +368,94 @@ private function multiexplode($delimiters, $string)
         $launch = explode($delimiters[0], $ready);
         return  $launch;
     }
+
+    /**
+     * Parse the `$docs['uri']` and attach `group` and `group_index` details.
+     *
+     * @param  array  $docs
+     * @return array  $docs
+     */
+    private function groupDocsByAPIURI(array $docs): array
+    {
+        $patterns = config('request-docs.group_by.uri_patterns', []);
+
+        $regex = count($patterns) > 0 ? '(' . implode('|', $patterns) . ')' : '';
+
+        // A collection<string, int> to remember indexes with `group` => `index` pair.
+        $groupIndexes = collect();
+
+        foreach ($docs as $i => $doc) {
+            if ($regex !== '') {
+                // If $regex    = '^api/v[\d]+/',
+                // and $uri     = '/api/v1/users',
+                // then $prefix = '/api/v1/'.
+                $prefix = Str::match($regex, $doc['uri']);
+            }
+
+            $group = $this->getGroupByURI($prefix ?? '', $doc['uri']);
+            $groupIndexes = $this->rememberGroupIndex($groupIndexes, $group);
+            $docs[$i] = $this->attachGroupInfo($doc, $group, $groupIndexes->get($group));
+        }
+
+        return $docs;
+    }
+
+    /**
+     * Create and return group name by the `$uri`.
+     */
+    private function getGroupByURI(string $prefix, string $uri): string
+    {
+        if ($prefix === '') {
+            // No prefix, create group by the first path.
+            $paths = explode('/', $uri);
+            return $paths[0];
+        }
+
+        // Glue the prefix + "first path after prefix" to form a group.
+        $after = (Str::after($uri, $prefix));
+        $paths = explode('/', $after);
+        return $prefix . $paths[0];
+    }
+
+    /**
+     * Parse the `$docs['controller_full_path']` and attach `group` and `group_index` details.
+     */
+    private function groupDocsByFQController(array $docs): array
+    {
+        // To remember group indexes with group => index pair.
+        $groupIndexes = collect();
+
+        foreach ($docs as $i => $doc) {
+            $group = $doc['controller_full_path'];
+            $groupIndexes = $this->rememberGroupIndex($groupIndexes, $group);
+            $docs[$i] = $this->attachGroupInfo($doc, $group, $groupIndexes->get($group));
+        }
+        return $docs;
+    }
+
+    /**
+     * Set the last index number into `$groupIndexes`
+     *
+     * @param  \Illuminate\Support\Collection<string, int>  $groupIndexes  [`group` => `index`]
+     */
+    private function rememberGroupIndex(Collection $groupIndexes, string $key): Collection
+    {
+        if (!$groupIndexes->has($key)) {
+            $groupIndexes->put($key, 0);
+            return $groupIndexes;
+        }
+
+        $groupIndexes->put($key, $groupIndexes->get($key) + 1);
+        return $groupIndexes;
+    }
+
+    /**
+     * Attach `group` and `group_index` into `$doc`.
+     */
+    private function attachGroupInfo(array $doc, string $group, int $groupIndex): array
+    {
+        $doc['group'] = $group;
+        $doc['group_index'] = $groupIndex;
+        return $doc;
+    }
 }