Improve variables naming, add missing docblocks

src/Tools/ResponseResolver.php

@@ -3,11 +3,11 @@
 namespace Mpociot\ApiDoc\Tools;
 
 use Illuminate\Routing\Route;
-use Illuminate\Http\JsonResponse;
 use Mpociot\ApiDoc\Tools\ResponseStrategies\ResponseTagStrategy;
 use Mpociot\ApiDoc\Tools\ResponseStrategies\ResponseCallStrategy;
 use Mpociot\ApiDoc\Tools\ResponseStrategies\ResponseFileStrategy;
 use Mpociot\ApiDoc\Tools\ResponseStrategies\TransformerTagsStrategy;
+use Symfony\Component\HttpFoundation\Response;
 
 class ResponseResolver
 {
@@ -38,28 +38,24 @@ class ResponseResolver
      * @param array $tags
      * @param array $routeProps
      *
-     * @return array
+     * @return array|null
      */
     private function resolve(array $tags, array $routeProps)
     {
-        $response = null;
-
         foreach (static::$strategies as $strategy) {
             $strategy = new $strategy();
 
-            /** @var JsonResponse|array|null $response */
-            $response = $strategy($this->route, $tags, $routeProps);
+            /** @var Response[]|null $response */
+            $responses = $strategy($this->route, $tags, $routeProps);
 
-            if (! is_null($response)) {
-                if (is_array($response)) {
-                    return array_map(function (JsonResponse $response) {
-                        return ['status' => $response->getStatusCode(), 'content' => $this->getResponseContent($response)];
-                    }, $response);
-                }
-
-                return [['status' => $response->getStatusCode(), 'content' => $this->getResponseContent($response)]];
+            if (! is_null($responses)) {
+                return array_map(function (Response $response) {
+                    return ['status' => $response->getStatusCode(), 'content' => $this->getResponseContent($response)];
+                }, $responses);
             }
         }
+
+        return null;
     }
 
     /**

src/Tools/ResponseStrategies/ResponseCallStrategy.php

@@ -12,17 +12,25 @@ use Illuminate\Routing\Route;
  */
 class ResponseCallStrategy
 {
+    /**
+     * @param Route $route
+     * @param array $tags
+     * @param array $routeProps
+     *
+     * @return array|null
+     */
     public function __invoke(Route $route, array $tags, array $routeProps)
     {
         $rulesToApply = $routeProps['rules']['response_calls'] ?? [];
         if (! $this->shouldMakeApiCall($route, $rulesToApply)) {
-            return;
+            return null;
         }
 
         $this->configureEnvironment($rulesToApply);
         $request = $this->prepareRequest($route, $rulesToApply, $routeProps['body'], $routeProps['query']);
+
         try {
-            $response = $this->makeApiCall($request);
+            $response = [$this->makeApiCall($request)];
         } catch (\Exception $e) {
             $response = null;
         } finally {
@@ -32,12 +40,25 @@ class ResponseCallStrategy
         return $response;
     }
 
+    /**
+     * @param array $rulesToApply
+     *
+     * @return void
+     */
     private function configureEnvironment(array $rulesToApply)
     {
         $this->startDbTransaction();
         $this->setEnvironmentVariables($rulesToApply['env'] ?? []);
     }
 
+    /**
+     * @param Route $route
+     * @param array $rulesToApply
+     * @param array $bodyParams
+     * @param array $queryParams
+     *
+     * @return Request
+     */
     private function prepareRequest(Route $route, array $rulesToApply, array $bodyParams, array $queryParams)
     {
         $uri = $this->replaceUrlParameterBindings($route, $rulesToApply['bindings'] ?? []);
@@ -77,6 +98,11 @@ class ResponseCallStrategy
         return $uri;
     }
 
+    /**
+     * @param array $env
+     *
+     * @return void
+     */
     private function setEnvironmentVariables(array $env)
     {
         foreach ($env as $name => $value) {
@@ -87,6 +113,9 @@ class ResponseCallStrategy
         }
     }
 
+    /**
+     * @return void
+     */
     private function startDbTransaction()
     {
         try {
@@ -95,6 +124,9 @@ class ResponseCallStrategy
         }
     }
 
+    /**
+     * @return void
+     */
     private function endDbTransaction()
     {
         try {
@@ -103,11 +135,19 @@ class ResponseCallStrategy
         }
     }
 
+    /**
+     * @return void
+     */
     private function finish()
     {
         $this->endDbTransaction();
     }
 
+    /**
+     * @param Request $request
+     *
+     * @return \Illuminate\Http\JsonResponse|mixed
+     */
     public function callDingoRoute(Request $request)
     {
         /** @var Dispatcher $dispatcher */
@@ -138,11 +178,23 @@ class ResponseCallStrategy
         return $response;
     }
 
+    /**
+     * @param Route $route
+     *
+     * @return array
+     */
     public function getMethods(Route $route)
     {
         return array_diff($route->methods(), ['HEAD']);
     }
 
+    /**
+     * @param Request $request
+     * @param Route $route
+     * @param array|null $headers
+     *
+     * @return Request
+     */
     private function addHeaders(Request $request, Route $route, $headers)
     {
         // set the proper domain
@@ -162,6 +214,12 @@ class ResponseCallStrategy
         return $request;
     }
 
+    /**
+     * @param Request $request
+     * @param array $query
+     *
+     * @return Request
+     */
     private function addQueryParameters(Request $request, array $query)
     {
         $request->query->add($query);
@@ -170,6 +228,12 @@ class ResponseCallStrategy
         return $request;
     }
 
+    /**
+     * @param Request $request
+     * @param array $body
+     *
+     * @return Request
+     */
     private function addBodyParameters(Request $request, array $body)
     {
         $request->request->add($body);
@@ -177,6 +241,12 @@ class ResponseCallStrategy
         return $request;
     }
 
+    /**
+     * @param Request $request
+     *
+     * @return \Illuminate\Http\JsonResponse|mixed|\Symfony\Component\HttpFoundation\Response
+     * @throws \Exception
+     */
     private function makeApiCall(Request $request)
     {
         if (config('apidoc.router') == 'dingo') {
@@ -189,9 +259,10 @@ class ResponseCallStrategy
     }
 
     /**
-     * @param $request
+     * @param Request $request
      *
      * @return \Symfony\Component\HttpFoundation\Response
+     * @throws \Exception
      */
     private function callLaravelRoute(Request $request): \Symfony\Component\HttpFoundation\Response
     {
@@ -202,6 +273,12 @@ class ResponseCallStrategy
         return $response;
     }
 
+    /**
+     * @param Route $route
+     * @param array $rulesToApply
+     *
+     * @return bool
+     */
     private function shouldMakeApiCall(Route $route, array $rulesToApply): bool
     {
         $allowedMethods = $rulesToApply['methods'] ?? [];

src/Tools/ResponseStrategies/ResponseFileStrategy.php

@@ -16,11 +16,11 @@ class ResponseFileStrategy
      * @param array $tags
      * @param array $routeProps
      *
-     * @return mixed
+     * @return array|null
      */
     public function __invoke(Route $route, array $tags, array $routeProps)
     {
-        return $this->getFileResponse($tags);
+        return $this->getFileResponses($tags);
     }
 
     /**
@@ -28,19 +28,19 @@ class ResponseFileStrategy
      *
      * @param array $tags
      *
-     * @return mixed
+     * @return array|null
      */
-    protected function getFileResponse(array $tags)
+    protected function getFileResponses(array $tags)
     {
         $responseFileTags = array_filter($tags, function ($tag) {
             return $tag instanceof Tag && strtolower($tag->getName()) === 'responsefile';
         });
 
         if (empty($responseFileTags)) {
-            return;
+            return null;
         }
 
-        return array_map(function ($responseFileTag) {
+        return array_map(function (Tag $responseFileTag) {
             preg_match('/^(\d{3})?\s?([\s\S]*)$/', $responseFileTag->getContent(), $result);
 
             $status = $result[1] ?: 200;

src/Tools/ResponseStrategies/ResponseTagStrategy.php

@@ -16,11 +16,11 @@ class ResponseTagStrategy
      * @param array $tags
      * @param array $routeProps
      *
-     * @return mixed
+     * @return array|null
      */
     public function __invoke(Route $route, array $tags, array $routeProps)
     {
-        return $this->getDocBlockResponse($tags);
+        return $this->getDocBlockResponses($tags);
     }
 
     /**
@@ -28,19 +28,19 @@ class ResponseTagStrategy
      *
      * @param array $tags
      *
-     * @return mixed
+     * @return array|null
      */
-    protected function getDocBlockResponse(array $tags)
+    protected function getDocBlockResponses(array $tags)
     {
         $responseTags = array_filter($tags, function ($tag) {
             return $tag instanceof Tag && strtolower($tag->getName()) === 'response';
         });
 
         if (empty($responseTags)) {
-            return;
+            return null;
         }
 
-        return array_map(function ($responseTag) {
+        return array_map(function (Tag $responseTag) {
             preg_match('/^(\d{3})?\s?([\s\S]*)$/', $responseTag->getContent(), $result);
 
             $status = $result[1] ?: 200;

src/Tools/ResponseStrategies/TransformerTagsStrategy.php

@@ -15,6 +15,13 @@ use League\Fractal\Resource\Collection;
  */
 class TransformerTagsStrategy
 {
+    /**
+     * @param Route $route
+     * @param array $tags
+     * @param array $routeProps
+     *
+     * @return array|null
+     */
     public function __invoke(Route $route, array $tags, array $routeProps)
     {
         return $this->getTransformerResponse($tags);
@@ -25,13 +32,13 @@ class TransformerTagsStrategy
      *
      * @param array $tags
      *
-     * @return mixed
+     * @return array|null
      */
     protected function getTransformerResponse(array $tags)
     {
         try {
             if (empty($transformerTag = $this->getTransformerTag($tags))) {
-                return;
+                return null;
             }
 
             $transformer = $this->getTransformerClass($transformerTag);
@@ -43,9 +50,9 @@ class TransformerTagsStrategy
                 ? new Collection([$modelInstance, $modelInstance], new $transformer)
                 : new Item($modelInstance, new $transformer);
 
-            return response($fractal->createData($resource)->toJson());
+            return [response($fractal->createData($resource)->toJson())];
         } catch (\Exception $e) {
-            return;
+            return null;
         }
     }