feat: Store documentation file on a configurable directory

config/auto-doc.php

@@ -128,7 +128,8 @@
     'drivers' => [
         'local' => [
             'class' => LocalDriver::class,
-            'production_path' => storage_path('documentation.json'),
+            'directory' => 'documentations',
+            'base_file_name' => 'documentation',
         ],
         'remote' => [
             'class' => RemoteDriver::class,
@@ -146,7 +147,8 @@
             | One of the filesystems.disks config value
             */
             'disk' => env('SWAGGER_STORAGE_DRIVER_DISK', 'public'),
-            'production_path' => 'documentation.json',
+            'directory' => 'documentations',
+            'base_file_name' => 'documentation',
         ],
     ],
 
@@ -184,5 +186,5 @@
         'development',
     ],
 
-    'config_version' => '2.8',
+    'config_version' => '2.9',
 ];

src/Drivers/LocalDriver.php

@@ -7,33 +7,46 @@
 
 class LocalDriver extends BaseDriver
 {
-    protected ?string $prodFilePath;
+    protected ?string $mainFilePath;
+    protected array $config;
 
     public function __construct()
     {
         parent::__construct();
 
-        $this->prodFilePath = config('auto-doc.drivers.local.production_path');
+        $this->config = config('auto-doc.drivers.local', []);
 
-        if (empty($this->prodFilePath)) {
+        $directory = (str_ends_with($this->config['directory'], DIRECTORY_SEPARATOR))
+            ? $this->config['directory']
+            : $this->config['directory'] . DIRECTORY_SEPARATOR;
+
+        $this->mainFilePath = storage_path("{$directory}{$this->config['base_file_name']}.json");
+
+        if (empty($this->config['base_file_name']) || !str_ends_with($this->mainFilePath, '.json')) {
             throw new MissedProductionFilePathException();
         }
     }
 
     public function saveData(): void
     {
-        file_put_contents($this->prodFilePath, json_encode($this->getTmpData()));
+        $documentationDirectory = storage_path($this->config['directory']);
+
+        if (!is_dir($documentationDirectory)) {
+            mkdir($documentationDirectory);
+        }
+
+        file_put_contents($this->mainFilePath, json_encode($this->getTmpData()));
 
         $this->clearTmpData();
     }
 
     public function getDocumentation(): array
     {
-        if (!file_exists($this->prodFilePath)) {
+        if (!file_exists($this->mainFilePath)) {
             throw new FileNotFoundException();
         }
 
-        $fileContent = file_get_contents($this->prodFilePath);
+        $fileContent = file_get_contents($this->mainFilePath);
 
         return json_decode($fileContent, true);
     }

src/Drivers/StorageDriver.php

@@ -10,34 +10,39 @@
 class StorageDriver extends BaseDriver
 {
     protected Filesystem $disk;
-    protected ?string $prodFilePath;
+    protected ?string $mainFilePath;
+    protected array $config;
 
     public function __construct()
     {
         parent::__construct();
 
-        $this->disk = Storage::disk(config('auto-doc.drivers.storage.disk'));
-        $this->prodFilePath = config('auto-doc.drivers.storage.production_path');
+        $this->config = config('auto-doc.drivers.storage');
+        $this->disk = Storage::disk($this->config['disk']);
 
-        if (empty($this->prodFilePath)) {
+        $directory = $this->config['directory'] . DIRECTORY_SEPARATOR;
+
+        $this->mainFilePath = "{$directory}{$this->config['base_file_name']}.json";
+
+        if (empty($this->config['base_file_name']) || !str_ends_with($this->mainFilePath, '.json')) {
             throw new MissedProductionFilePathException();
         }
     }
 
     public function saveData(): void
     {
-        $this->disk->put($this->prodFilePath, json_encode($this->getTmpData()));
+        $this->disk->put($this->mainFilePath, json_encode($this->getTmpData()));
 
         $this->clearTmpData();
     }
 
     public function getDocumentation(): array
     {
-        if (!$this->disk->exists($this->prodFilePath)) {
+        if (!$this->disk->exists($this->mainFilePath)) {
             throw new FileNotFoundException();
         }
 
-        $fileContent = $this->disk->get($this->prodFilePath);
+        $fileContent = $this->disk->get($this->mainFilePath);
 
         return json_decode($fileContent, true);
     }

tests/AutoDocControllerTest.php

@@ -12,18 +12,17 @@ class AutoDocControllerTest extends TestCase
     use PHPMock;
 
     protected static array $documentation;
-    protected static string $localDriverFilePath;
 
     public function setUp(): void
     {
         parent::setUp();
 
-        self::$localDriverFilePath ??= __DIR__ . '/../storage/documentation.json';
         self::$documentation ??= $this->getJsonFixture('tmp_data');
 
-        file_put_contents(self::$localDriverFilePath, json_encode(self::$documentation));
+        file_put_contents(storage_path('documentation.json'), json_encode(self::$documentation));
 
-        config(['auto-doc.drivers.local.production_path' => self::$localDriverFilePath]);
+        config(['auto-doc.drivers.local.directory' => '']);
+        config(['auto-doc.drivers.local.base_file_name' => 'documentation']);
     }
 
     public function tearDown(): void
@@ -42,6 +41,22 @@ public function testGetJSONDocumentation()
         $response->assertJson(self::$documentation);
     }
 
+    public function testGetJSONDocumentationWithFilledDirectory()
+    {
+        if (!is_dir(storage_path('documentations'))) {
+            mkdir(storage_path('documentations'));
+        }
+
+        file_put_contents(storage_path('documentations/documentation.json'), json_encode(self::$documentation));
+        config(['auto-doc.drivers.local.directory' => 'documentations']);
+
+        $response = $this->json('get', '/auto-doc/documentation');
+
+        $response->assertStatus(Response::HTTP_OK);
+
+        $response->assertJson(self::$documentation);
+    }
+
     public function testGetJSONDocumentationWithAdditionalPaths()
     {
         config([

tests/LocalDriverTest.php

@@ -9,24 +9,37 @@
 class LocalDriverTest extends TestCase
 {
     protected static LocalDriver $localDriverClass;
-    protected static string $productionFilePath;
+    protected static string $baseFile;
     protected static string $tmpDocumentationFilePath;
     protected static array $tmpData;
 
     public function setUp(): void
     {
         parent::setUp();
 
-        self::$productionFilePath ??= __DIR__ . '/../storage/documentation.json';
-        self::$tmpDocumentationFilePath ??= __DIR__ . '/../storage/temp_documentation.json';
+        $documentationDirectory = config('auto-doc.drivers.local.directory');
+
+        self::$baseFile ??= storage_path("{$documentationDirectory}/documentation.json");
+        self::$tmpDocumentationFilePath ??= storage_path('temp_documentation.json');
 
         self::$tmpData ??= $this->getJsonFixture('tmp_data');
 
-        config(['auto-doc.drivers.local.production_path' => self::$productionFilePath]);
+        config(['auto-doc.drivers.local.base_file_name' => 'documentation']);
 
         self::$localDriverClass ??= new LocalDriver();
     }
 
+    public function testDirectoryEndsWithDirectorySeparator()
+    {
+        config(['auto-doc.drivers.local.directory' => 'documentations'.DIRECTORY_SEPARATOR]);
+
+        $driver = new LocalDriver();
+        $driver->saveTmpData(self::$tmpData);
+
+        $this->assertFileExists(self::$tmpDocumentationFilePath);
+        $this->assertFileEquals($this->generateFixturePath('tmp_data_non_formatted.json'), self::$tmpDocumentationFilePath);
+    }
+
     public function testSaveTmpData()
     {
         self::$localDriverClass->saveTmpData(self::$tmpData);
@@ -55,7 +68,7 @@ public function testCreateClassConfigEmpty()
     {
         $this->expectException(MissedProductionFilePathException::class);
 
-        config(['auto-doc.drivers.local.production_path' => null]);
+        config(['auto-doc.drivers.local.base_file_name' => null]);
 
         new LocalDriver();
     }
@@ -73,15 +86,32 @@ public function testSaveData()
 
         self::$localDriverClass->saveData();
 
-        $this->assertFileExists(self::$productionFilePath);
-        $this->assertFileEquals($this->generateFixturePath('tmp_data_non_formatted.json'), self::$productionFilePath);
+        $this->assertFileExists(self::$baseFile);
+        $this->assertFileEquals($this->generateFixturePath('tmp_data_non_formatted.json'), self::$baseFile);
+
+        $this->assertFileDoesNotExist(self::$tmpDocumentationFilePath);
+    }
+
+    public function testSaveDataWhenDirectoryNotExists()
+    {
+        $documentationDirectory = 'test_directory';
+        if (is_dir($documentationDirectory)) {
+            rmdir(storage_path($documentationDirectory));
+        }
+
+        self::$localDriverClass->saveTmpData(self::$tmpData);
+
+        self::$localDriverClass->saveData();
+
+        $this->assertFileExists(self::$baseFile);
+        $this->assertFileEquals($this->generateFixturePath('tmp_data_non_formatted.json'), self::$baseFile);
 
         $this->assertFileDoesNotExist(self::$tmpDocumentationFilePath);
     }
 
     public function testGetDocumentation()
     {
-        file_put_contents(self::$productionFilePath, json_encode(self::$tmpData));
+        file_put_contents(self::$baseFile, json_encode(self::$tmpData));
 
         $documentation = self::$localDriverClass->getDocumentation();
 
@@ -92,7 +122,7 @@ public function testGetDocumentationFileNotExists()
     {
         $this->expectException(FileNotFoundException::class);
 
-        config(['auto-doc.drivers.local.production_path' => 'not_exists_file']);
+        config(['auto-doc.drivers.local.base_file_name' => 'not_exists_file.json']);
 
         (new LocalDriver())->getDocumentation();
     }

tests/RemoteDriverTest.php

@@ -20,7 +20,7 @@ public function setUp(): void
         parent::setUp();
 
         self::$tmpData ??= $this->getJsonFixture('tmp_data');
-        self::$tmpDocumentationFilePath ??= __DIR__ . '/../storage/temp_documentation.json';
+        self::$tmpDocumentationFilePath ??= storage_path('temp_documentation.json');
 
         self::$remoteDriverClass ??= new RemoteDriver();
     }

tests/StorageDriverTest.php

@@ -12,7 +12,7 @@ class StorageDriverTest extends TestCase
 {
     protected static StorageDriver $storageDriverClass;
     protected Filesystem $disk;
-    protected static string $productionFilePath;
+    protected static string $baseFile;
     protected static string $tmpDocumentationFilePath;
     protected static array $tmpData;
 
@@ -22,16 +22,28 @@ public function setUp(): void
 
         $this->disk = Storage::fake('testing');
 
-        self::$productionFilePath ??= 'documentation.json';
-        self::$tmpDocumentationFilePath ??= __DIR__ . '/../storage/temp_documentation.json';
+        $documentationDirectory = config('auto-doc.drivers.storage.directory');
+
+        self::$baseFile ??= "{$documentationDirectory}/documentation.json";
+        self::$tmpDocumentationFilePath ??= storage_path('temp_documentation.json');
 
         self::$tmpData ??= $this->getJsonFixture('tmp_data');
 
         config(['auto-doc.drivers.storage.disk' => 'testing']);
-        config(['auto-doc.drivers.storage.production_path' => self::$productionFilePath]);
+        config(['auto-doc.drivers.storage.base_file_name' => 'documentation']);
 
         self::$storageDriverClass = new StorageDriver();
     }
+    public function testDirectoryEndsWithDirectorySeparator()
+    {
+        config(['auto-doc.drivers.storage.directory' => 'documentations'.DIRECTORY_SEPARATOR]);
+
+        $driver = new StorageDriver();
+        $driver->saveTmpData(self::$tmpData);
+
+        $this->assertFileExists(self::$tmpDocumentationFilePath);
+        $this->assertFileEquals($this->generateFixturePath('tmp_data_non_formatted.json'), self::$tmpDocumentationFilePath);
+    }
 
     public function testSaveTmpData()
     {
@@ -61,7 +73,7 @@ public function testCreateClassConfigEmpty()
     {
         $this->expectException(MissedProductionFilePathException::class);
 
-        config(['auto-doc.drivers.storage.production_path' => null]);
+        config(['auto-doc.drivers.storage.base_file_name' => null]);
 
         new StorageDriver();
     }
@@ -79,15 +91,15 @@ public function testSaveData()
 
         self::$storageDriverClass->saveData();
 
-        $this->disk->assertExists(self::$productionFilePath);
-        $this->assertEqualsFixture('tmp_data_non_formatted.json', $this->disk->get(self::$productionFilePath));
+        $this->disk->assertExists(self::$baseFile);
+        $this->assertEqualsFixture('tmp_data_non_formatted.json', $this->disk->get(self::$baseFile));
 
         $this->assertFileDoesNotExist(self::$tmpDocumentationFilePath);
     }
 
     public function testGetDocumentation()
     {
-        $this->disk->put(self::$productionFilePath, $this->getFixture('tmp_data_non_formatted.json'));
+        $this->disk->put(self::$baseFile, $this->getFixture('tmp_data_non_formatted.json'));
 
         $documentation = self::$storageDriverClass->getDocumentation();