Merge pull request #623 from robbieaverill/feature/non-existent-responsefiles

Non-existent `@responseFile` annotations now show a warning for the route

src/Commands/GenerateDocumentation.php

@@ -98,11 +98,21 @@ class GenerateDocumentation extends Command
         foreach ($routes as $routeItem) {
             $route = $routeItem['route'];
             /** @var Route $route */
-            if ($this->isValidRoute($route) && $this->isRouteVisibleForDocumentation($route->getAction())) {
+
+            $messageFormat = '%s route: [%s] %s';
+            $routeMethods = implode(',', $generator->getMethods($route));
+            $routePath = $generator->getUri($route);
+
+            if (!$this->isValidRoute($route) || !$this->isRouteVisibleForDocumentation($route->getAction())) {
+                $this->warn(sprintf($messageFormat, 'Skipping', $routeMethods, $routePath));
+                continue;
+            }
+
+            try {
                 $parsedRoutes[] = $generator->processRoute($route, $routeItem['apply'] ?? []);
-                $this->info('Processed route: ['.implode(',', $generator->getMethods($route)).'] '.$generator->getUri($route));
-            } else {
-                $this->warn('Skipping route: ['.implode(',', $generator->getMethods($route)).'] '.$generator->getUri($route));
+                $this->info(sprintf($messageFormat, 'Processed', $routeMethods, $routePath));
+            } catch (\Exception $exception) {
+                $this->warn(sprintf($messageFormat, 'Skipping', $routeMethods, $routePath) . ' - ' . $exception->getMessage());
             }
         }
 

src/Extracting/Strategies/Responses/UseResponseFileTag.php

@@ -20,7 +20,7 @@ class UseResponseFileTag extends Strategy
      * @param array $routeRules
      * @param array $context
      *
-     * @throws \Exception
+     * @throws \Exception If the response file does not exist
      *
      * @return array|null
      */
@@ -55,8 +55,13 @@ class UseResponseFileTag extends Strategy
 
         $responses = array_map(function (Tag $responseFileTag) {
             preg_match('/^(\d{3})?\s?([\S]*[\s]*?)(\{.*\})?$/', $responseFileTag->getContent(), $result);
+            $relativeFilePath = trim($result[2]);
+            $filePath = storage_path($relativeFilePath);
+            if (!file_exists($filePath)) {
+                throw new \Exception('@responseFile ' . $relativeFilePath . ' does not exist');
+            }
             $status = $result[1] ?: 200;
-            $content = $result[2] ? file_get_contents(storage_path(trim($result[2])), true) : '{}';
+            $content = $result[2] ? file_get_contents($filePath, true) : '{}';
             $json = ! empty($result[3]) ? str_replace("'", '"', $result[3]) : '{}';
             $merged = array_merge(json_decode($content, true), json_decode($json, true));
 

tests/Fixtures/TestController.php

@@ -358,4 +358,12 @@ class TestController extends Controller
     {
         return '';
     }
+
+    /**
+     * @responseFile i-do-not-exist.json
+     */
+    public function withNonExistentResponseFile()
+    {
+        return '';
+    }
 }

tests/GenerateDocumentationTest.php

@@ -114,6 +114,18 @@ class GenerateDocumentationTest extends TestCase
         $this->assertContains('Processed route: [GET] api/test', $output);
     }
 
+    /** @test */
+    public function can_skip_non_existent_response_files()
+    {
+        RouteFacade::get('/api/non-existent', TestController::class.'@withNonExistentResponseFile');
+
+        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
+        $output = $this->artisan('apidoc:generate');
+
+        $this->assertContains('Skipping route: [GET] api/non-existent', $output);
+        $this->assertContains('@responseFile i-do-not-exist.json does not exist', $output);
+    }
+
     /** @test */
     public function can_parse_resource_routes()
     {