Move `groupName`, `groupDescription`, `title`, `description`, and `authenticated` into parsed route `metadata`

docs/generating-documentation.md

@@ -48,11 +48,11 @@ php artisan apidoc:rebuild
  This will copy the views files to `\resources\views\vendor\apidoc`.
  
  - Next, create a file called {language-name}.blade.php (for example, ruby.blade.php) in the partials/example-requests directory. You can then write Markdown with Blade templating that describes how the example request for the language should be rendered. You have the `$route` variable available to you. This variable is an array with the following keys:
-    - `methods`: an array of the HTTP methods for that route
-    - `boundUri`: the complete URL for the route, with any url parameters replaced (/users/{id} -> /users/1)
-    - `headers`: key-value array of headers to be sent with route (according to your configuration)
-    - `cleanQueryParameters`: key-value array of query parameters with example values to be sent with the request. Parameters which have been excluded from the example requests (see [Example Parameters](documenting.html#example-parameters)) will not be present here.
-    - `cleanBodyParameters`: key-value array of body parameters with example values to be sent with the request. Parameters which have been excluded from the example requests (see [Example Parameters](documenting.html#example-parameters)) will not be present here.
+- `methods`: an array of the HTTP methods for that route
+- `boundUri`: the complete URL for the route, with any url parameters replaced (/users/{id} -> /users/1)
+- `headers`: key-value array of headers to be sent with route (according to your configuration)
+- `cleanQueryParameters`: key-value array of query parameters with example values to be sent with the request. Parameters which have been excluded from the example requests (see [Example Parameters](documenting.html#example-parameters)) will not be present here.
+- `cleanBodyParameters`: key-value array of body parameters with example values to be sent with the request. Parameters which have been excluded from the example requests (see [Example Parameters](documenting.html#example-parameters)) will not be present here.
 
 - Add the language to the `example_languages` array in the package config.
 

resources/views/documentarian.blade.php

@@ -8,7 +8,7 @@
 @foreach($parsedRoutes as $groupName => $routes)
 #{!! $groupName !!}
 {{-- We pick the first non-empty description we see. --}}
-{!! \Illuminate\Support\Arr::first($routes, function ($route) { return $route['groupDescription'] !== ''; })['groupDescription'] ?? '' !!}
+{!! \Illuminate\Support\Arr::first($routes, function ($route) { return $route['metadata']['groupDescription'] !== ''; })['metadata']['groupDescription'] ?? '' !!}
 @foreach($routes as $parsedRoute)
 @if($writeCompareFile === true)
 {!! $parsedRoute['output'] !!}

resources/views/partials/route.blade.php

@@ -1,12 +1,12 @@
 <!-- START_{{$route['id']}} -->
-@if($route['title'] != '')## {{ $route['title']}}
+@if($route['metadata']['title'] != '')## {{ $route['metadata']['title']}}
 @else## {{$route['uri']}}@endif
-@if($route['authenticated'])
+@if($route['metadata']['authenticated'])
 
 <br><small style="padding: 1px 9px 2px;font-weight: bold;white-space: nowrap;color: #ffffff;-webkit-border-radius: 9px;-moz-border-radius: 9px;border-radius: 9px;background-color: #3a87ad;">Requires authentication</small>@endif
-@if($route['description'])
+@if($route['metadata']['description'])
 
-{!! $route['description'] !!}
+{!! $route['metadata']['description'] !!}
 @endif
 
 > Example request:

src/Commands/GenerateDocumentation.php

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

src/Postman/CollectionWriter.php

@@ -58,7 +58,7 @@ class CollectionWriter
                         $mode = $route['methods'][0] === 'PUT' ? 'urlencoded' : 'formdata';
 
                         return [
-                            'name' => $route['title'] != '' ? $route['title'] : url($route['uri']),
+                            'name' => $route['metadata']['title'] != '' ? $route['metadata']['title'] : url($route['uri']),
                             'request' => [
                                 'url' => url($route['uri']).(collect($route['queryParameters'])->isEmpty()
                                     ? ''
@@ -88,7 +88,7 @@ class CollectionWriter
                                         ];
                                     })->values()->toArray(),
                                 ],
-                                'description' => $route['description'],
+                                'description' => $route['metadata']['description'],
                                 'response' => [],
                             ],
                         ];

src/Tools/Generator.php

@@ -80,8 +80,6 @@ class Generator
 
         $parsedRoute['headers'] = $routeRules['headers'] ?? [];
 
-        $parsedRoute += $metadata;
-
         return $parsedRoute;
     }
 

tests/GenerateDocumentationTest.php

@@ -37,7 +37,7 @@ class GenerateDocumentationTest extends TestCase
 
     public function tearDown(): void
     {
-             Utils::deleteDirectoryAndContents('/public/docs');
+        Utils::deleteDirectoryAndContents('/public/docs');
     }
 
     /**

tests/Unit/GeneratorTestCase.php

@@ -24,12 +24,15 @@ abstract class GeneratorTestCase extends TestCase
             'metadata' => [
                 \Mpociot\ApiDoc\Strategies\Metadata\GetFromDocBlocks::class,
             ],
-            'bodyParameters' => [
-                \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+            'urlParameters' => [
+                \Mpociot\ApiDoc\Strategies\UrlParameters\GetFromUrlParamTag::class,
             ],
             'queryParameters' => [
                 \Mpociot\ApiDoc\Strategies\QueryParameters\GetFromQueryParamTag::class,
             ],
+            'bodyParameters' => [
+                \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+            ],
             'responses' => [
                 \Mpociot\ApiDoc\Strategies\Responses\UseResponseTag::class,
                 \Mpociot\ApiDoc\Strategies\Responses\UseResponseFileTag::class,
@@ -75,8 +78,8 @@ abstract class GeneratorTestCase extends TestCase
         $route = $this->createRoute('GET', '/api/test', 'withEndpointDescription');
         $parsed = $this->generator->processRoute($route);
 
-        $this->assertSame('Example title.', $parsed['title']);
-        $this->assertSame("This will be the long description.\nIt can also be multiple lines long.", $parsed['description']);
+        $this->assertSame('Example title.', $parsed['metadata']['title']);
+        $this->assertSame("This will be the long description.\nIt can also be multiple lines long.", $parsed['metadata']['description']);
     }
 
     /** @test */
@@ -326,7 +329,7 @@ abstract class GeneratorTestCase extends TestCase
     public function can_parse_route_group()
     {
         $route = $this->createRoute('GET', '/api/test', 'dummy');
-        $routeGroup = $this->generator->processRoute($route)['groupName'];
+        $routeGroup = $this->generator->processRoute($route)['metadata']['groupName'];
 
         $this->assertSame('Group A', $routeGroup);
     }
@@ -336,37 +339,37 @@ abstract class GeneratorTestCase extends TestCase
     {
         $route = $this->createRoute('GET', '/group/1', 'withGroupOverride');
         $parsedRoute = $this->generator->processRoute($route);
-        $this->assertSame('Group B', $parsedRoute['groupName']);
-        $this->assertSame('', $parsedRoute['groupDescription']);
+        $this->assertSame('Group B', $parsedRoute['metadata']['groupName']);
+        $this->assertSame('', $parsedRoute['metadata']['groupDescription']);
 
         $route = $this->createRoute('GET', '/group/2', 'withGroupOverride2');
         $parsedRoute = $this->generator->processRoute($route);
-        $this->assertSame('Group B', $parsedRoute['groupName']);
-        $this->assertSame('', $parsedRoute['groupDescription']);
-        $this->assertSame('This is also in Group B. No route description. Route title before gropp.', $parsedRoute['title']);
+        $this->assertSame('Group B', $parsedRoute['metadata']['groupName']);
+        $this->assertSame('', $parsedRoute['metadata']['groupDescription']);
+        $this->assertSame('This is also in Group B. No route description. Route title before gropp.', $parsedRoute['metadata']['title']);
 
         $route = $this->createRoute('GET', '/group/3', 'withGroupOverride3');
         $parsedRoute = $this->generator->processRoute($route);
-        $this->assertSame('Group B', $parsedRoute['groupName']);
-        $this->assertSame('', $parsedRoute['groupDescription']);
-        $this->assertSame('This is also in Group B. Route title after group.', $parsedRoute['title']);
+        $this->assertSame('Group B', $parsedRoute['metadata']['groupName']);
+        $this->assertSame('', $parsedRoute['metadata']['groupDescription']);
+        $this->assertSame('This is also in Group B. Route title after group.', $parsedRoute['metadata']['title']);
 
         $route = $this->createRoute('GET', '/group/4', 'withGroupOverride4');
         $parsedRoute = $this->generator->processRoute($route);
-        $this->assertSame('Group C', $parsedRoute['groupName']);
-        $this->assertSame('Group description after group.', $parsedRoute['groupDescription']);
-        $this->assertSame('This is in Group C. Route title before group.', $parsedRoute['title']);
+        $this->assertSame('Group C', $parsedRoute['metadata']['groupName']);
+        $this->assertSame('Group description after group.', $parsedRoute['metadata']['groupDescription']);
+        $this->assertSame('This is in Group C. Route title before group.', $parsedRoute['metadata']['title']);
     }
 
     /** @test */
     public function can_parse_auth_tags()
     {
         $route = $this->createRoute('GET', '/api/test', 'withAuthenticatedTag');
-        $authenticated = $this->generator->processRoute($route)['authenticated'];
+        $authenticated = $this->generator->processRoute($route)['metadata']['authenticated'];
         $this->assertTrue($authenticated);
 
         $route = $this->createRoute('GET', '/api/test', 'dummy');
-        $authenticated = $this->generator->processRoute($route)['authenticated'];
+        $authenticated = $this->generator->processRoute($route)['metadata']['authenticated'];
         $this->assertFalse($authenticated);
     }
 
@@ -932,8 +935,8 @@ abstract class GeneratorTestCase extends TestCase
 
         $parsed = $this->generator->processRoute($route);
 
-        $this->assertSame('Example title.', $parsed['title']);
-        $this->assertSame("This will be the long description.\nIt can also be multiple lines long.", $parsed['description']);
+        $this->assertSame('Example title.', $parsed['metadata']['title']);
+        $this->assertSame("This will be the long description.\nIt can also be multiple lines long.", $parsed['metadata']['description']);
     }
 
     abstract public function createRoute(string $httpMethod, string $path, string $controllerMethod, $register = false, $class = TestController::class);