Added feature 344 to include @QueryParam annotation for query parameters

Author: Lawrence Agbani

resources/views/partials/route.blade.php

@@ -17,8 +17,8 @@
     @endif
 @endforeach
 @endif
-@if(count($parsedRoute['parameters'])) \
-@foreach($parsedRoute['parameters'] as $attribute => $parameter)
+@if(count($parsedRoute['bodyParameters'])) \
+@foreach($parsedRoute['bodyParameters'] as $attribute => $parameter)
     -d "{{$attribute}}"="{{$parameter['value']}}" @if(! ($loop->last))\
     @endif
 @endforeach
@@ -32,8 +32,8 @@
     "crossDomain": true,
     "url": "{{ rtrim(config('app.docs_url') ?: config('app.url'), '/') }}/{{ ltrim($parsedRoute['uri'], '/') }}",
     "method": "{{$parsedRoute['methods'][0]}}",
-    @if(count($parsedRoute['parameters']))
-"data": {!! str_replace("\n}","\n    }", str_replace('    ','        ',json_encode(array_combine(array_keys($parsedRoute['parameters']), array_map(function($param){ return $param['value']; },$parsedRoute['parameters'])), JSON_PRETTY_PRINT))) !!},
+    @if(count($parsedRoute['bodyParameters']))
+"data": {!! str_replace("\n}","\n    }", str_replace('    ','        ',json_encode(array_combine(array_keys($parsedRoute['bodyParameters']), array_map(function($param){ return $param['value']; },$parsedRoute['bodyParameters'])), JSON_PRETTY_PRINT))) !!},
     @endif
 "headers": {
         "accept": "application/json",
@@ -65,14 +65,23 @@
 `{{$method}} {{$parsedRoute['uri']}}`
 
 @endforeach
-@if(count($parsedRoute['parameters']))
-#### Parameters
+@if(count($parsedRoute['bodyParameters']))
+#### Body Parameters
 
 Parameter | Type | Status | Description
 --------- | ------- | ------- | ------- | -----------
-@foreach($parsedRoute['parameters'] as $attribute => $parameter)
+@foreach($parsedRoute['bodyParameters'] as $attribute => $parameter)
     {{$attribute}} | {{$parameter['type']}} | @if($parameter['required']) required @else optional @endif | {!! implode(' ',$parameter['description']) !!}
 @endforeach
 @endif
+@if(count($parsedRoute['queryParameters']))
+#### Query Parameters
+
+Parameter | Status | Description
+--------- | ------- | ------- | -----------
+@foreach($parsedRoute['queryParameters'] as $attribute => $parameter)
+    {{$attribute}} | @if($parameter['required']) required @else optional @endif | {!! implode(' ',$parameter['description']) !!}
+@endforeach
+@endif
 
 <!-- END_{{$parsedRoute['id']}} -->

src/Generators/AbstractGenerator.php

@@ -63,7 +63,8 @@ public function processRoute($route)
             'description' => $docBlock['long'],
             'methods' => $this->getMethods($route),
             'uri' => $this->getUri($route),
-            'parameters' => $this->getParametersFromDocBlock($docBlock['tags']),
+            'bodyParameters' => $this->getBodyParametersFromDocBlock($docBlock['tags']),
+            'queryParameters' => $this->getQueryParametersFromDocBlock($docBlock['tags']),
             'response' => $content,
             'showresponse' => ! empty($content),
         ];
@@ -103,7 +104,7 @@ protected function getDocblockResponse($tags)
      *
      * @return array
      */
-    protected function getParametersFromDocBlock($tags)
+    protected function getBodyParametersFromDocBlock($tags)
     {
         $parameters = collect($tags)
             ->filter(function ($tag) {
@@ -121,6 +122,28 @@ protected function getParametersFromDocBlock($tags)
         return $parameters;
     }
 
+    /**
+     * @param array $tags
+     *
+     * @return array
+     */
+    protected function getQueryParametersFromDocBlock($tags)
+    {
+        $parameters = collect($tags)
+            ->filter(function ($tag) {
+                return $tag instanceof Tag && $tag->getName() === 'queryParam';
+            })
+            ->mapWithKeys(function ($tag) {
+                preg_match('/(.+?)\s+(required\s+)?(.+)/', $tag->getContent(), $content);
+                list($_, $name, $required, $description) = $content;
+                $required = trim($required) == 'required' ? true : false;
+
+                return [$name => compact('description', 'required')];
+            })->toArray();
+
+        return $parameters;
+    }
+
     /**
      * @param  $route
      * @param  $bindings

src/Postman/CollectionWriter.php

@@ -44,7 +44,7 @@ public function getCollection()
                                 'method' => $route['methods'][0],
                                 'body' => [
                                     'mode' => 'formdata',
-                                    'formdata' => collect($route['parameters'])->map(function ($parameter, $key) {
+                                    'formdata' => collect($route['bodyParameters'])->map(function ($parameter, $key) {
                                         return [
                                             'key' => $key,
                                             'value' => isset($parameter['value']) ? $parameter['value'] : '',

tests/Fixtures/TestController.php

@@ -31,6 +31,15 @@ public function withBodyParameters()
         return '';
     }
 
+    /**
+     * @queryParam location_id required The id of the location.
+     * @queryParam filters  The filters.
+     */
+    public function withQueryParameters()
+    {
+        return '';
+    }
+
     public function checkCustomHeaders(Request $request)
     {
         return $request->headers->all();

tests/Unit/GeneratorTestCase.php

@@ -44,7 +44,7 @@ public function test_can_parse_endpoint_description()
     public function test_can_parse_body_parameters()
     {
         $route = $this->createRoute('GET', '/api/test', 'withBodyParameters');
-        $parameters = $this->generator->processRoute($route)['parameters'];
+        $bodyParameters = $this->generator->processRoute($route)['bodyParameters'];
 
         $this->assertArraySubset([
             'user_id' => [
@@ -57,7 +57,25 @@ public function test_can_parse_body_parameters()
                 'required' => false,
                 'description' => 'The id of the room.',
             ],
-        ], $parameters);
+        ], $bodyParameters);
+    }
+
+    /** @test */
+    public function test_can_parse_query_parameters()
+    {
+        $route = $this->createRoute('GET', '/api/test', 'withQueryParameters');
+        $queryParameters = $this->generator->processRoute($route)['queryParameters'];
+
+        $this->assertArraySubset([
+            'location_id' => [
+                'required' => true,
+                'description' => 'The id of the location.',
+            ],
+            'filters' => [
+                'required' => false,
+                'description' => 'The filters.',
+            ],
+        ], $queryParameters);
     }
 
     /** @test */