Skip to content

feat: Store documentation file on a configurable directory #152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 16 commits into
base: master
Choose a base branch
from
Open

feat: Store documentation file on a configurable directory #152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
748d424
Add `documentation_directory` key to the config file;
hans-thomas Dec 13, 2024
cc6d056
Update drivers;
hans-thomas Dec 13, 2024
4e1970f
Fix tests;
hans-thomas Dec 13, 2024
7d08de0
Increase config version;
hans-thomas Dec 13, 2024
a97158e
Fix `No such file or directory` error on running tests;
hans-thomas Dec 13, 2024
10705ea
The `directory` config key added to local and storage drivers;
hans-thomas Dec 20, 2024
8d25c0f
The `production_path` key renamed;
hans-thomas Dec 20, 2024
db649e9
Add `.json` extension to `base_file_name` attr and check target dir e…
hans-thomas Dec 28, 2024
9dd4951
Update tests;
hans-thomas Dec 28, 2024
0fa0b4b
Wip;
hans-thomas Dec 28, 2024
4a387c2
Making suggested changes;
hans-thomas Jan 21, 2025
b665010
Apply changes;
hans-thomas Jan 25, 2025
ebef239
Apply changes;
hans-thomas Feb 2, 2025
cef046b
Set empty directory in AutoDocControllerTest;
hans-thomas Feb 2, 2025
83b43b3
Cover new lines;
hans-thomas Feb 2, 2025
999f2c2
Apply new changes;
hans-thomas Feb 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions config/auto-doc.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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',
],
],

Expand Down Expand Up @@ -184,5 +186,5 @@
'development',
],

'config_version' => '2.8',
'config_version' => '2.9',
];
25 changes: 19 additions & 6 deletions src/Drivers/LocalDriver.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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']);
Copy link

Copilot AI Aug 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The directory path construction is inconsistent with the mainFilePath construction. When config['directory'] already ends with DIRECTORY_SEPARATOR, this will create the wrong directory path. Should use the same normalized $directory variable from lines 19-21.

Copilot uses AI. Check for mistakes.

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);
}
Expand Down
19 changes: 12 additions & 7 deletions src/Drivers/StorageDriver.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Copy link

Copilot AI Aug 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The directory separator is unconditionally added, which will create paths like 'documentations//' when the directory already ends with a separator. This should check if the directory already ends with a separator first, similar to the LocalDriver implementation.

Suggested change
$directory = $this->config['directory'] . DIRECTORY_SEPARATOR;
$directory = $this->config['directory'];
if (!str_ends_with($directory, DIRECTORY_SEPARATOR)) {
$directory .= DIRECTORY_SEPARATOR;
}

Copilot uses AI. Check for mistakes.

$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);
}
Expand Down
23 changes: 19 additions & 4 deletions tests/AutoDocControllerTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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([
Expand Down
48 changes: 39 additions & 9 deletions tests/LocalDriverTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Copy link
Collaborator

@DenTray DenTray Feb 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
$this->assertFileExists(self::$tmpDocumentationFilePath);
$this->assertFileExists(storage_path('documentations/documentation.json'));

Copy link
Contributor Author

@hans-thomas hans-thomas Feb 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These static properties are used several times in this class and I believe they are beneficial to keep tests simpler and improve the readability.

$this->assertFileEquals($this->generateFixturePath('tmp_data_non_formatted.json'), self::$tmpDocumentationFilePath);
}

public function testSaveTmpData()
{
self::$localDriverClass->saveTmpData(self::$tmpData);
Expand Down Expand Up @@ -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();
}
Expand All @@ -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)) {
Comment on lines +97 to +98
Copy link

Copilot AI Aug 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The test uses a hardcoded directory name that doesn't match the actual configuration being tested. This should use the same directory configuration as other tests for consistency and to properly test the actual functionality.

Suggested change
$documentationDirectory = 'test_directory';
if (is_dir($documentationDirectory)) {
$documentationDirectory = config('auto-doc.drivers.local.directory');
if (is_dir(storage_path($documentationDirectory))) {

Copilot uses AI. Check for mistakes.
rmdir(storage_path($documentationDirectory));
Copy link

Copilot AI Aug 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using rmdir() without checking if the directory is empty will fail if the directory contains files. Should use a recursive directory removal or ensure the directory is empty before attempting to remove it.

Copilot uses AI. Check for mistakes.
}

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();

Expand All @@ -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();
}
Expand Down
2 changes: 1 addition & 1 deletion tests/RemoteDriverTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
Expand Down
28 changes: 20 additions & 8 deletions tests/StorageDriverTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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()
{
Expand Down Expand Up @@ -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();
}
Expand All @@ -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();

Expand Down