Is there a demand to be able to track differences in exported OpenAPI documents line by line?

[coffee-r]

I used #277 as a reference for ideas.

I recognize that php artisan scramble:export returns json minimized to one line by default.

$ php artisan scramble:export
$ cat api.json
{"openapi":"3.1.0","info":{"title":"Laravel","version":"0.0.1"},"servers":[{"url":"http:\/\/localhost\/api"}]}

The idea was to include the generated JSON in version control. However, since the JSON is on a single line, it is difficult to track differences when changes are made.

To improve the readability and maintainability of JSON files, why not add an option to allow line breaks? This would enhance version control diffs and make it easier for developers to review changes.

While Scramble provides dynamic documentation generation, static documentation is beneficial for a variety of reasons, including:

• Version control: Static JSON files allow for better tracking of changes over time.
• Review: Cleanly printed JSON is easy for developers to read and review.

The following is a recommended implementation:

<?php

namespace Dedoc\Scramble\Console\Commands;

use Dedoc\Scramble\Generator;
use Dedoc\Scramble\Scramble;
use Illuminate\Console\Command;
use Illuminate\Support\Facades\File;

class ExportDocumentation extends Command
{
    protected $signature = 'scramble:export
        {--path= : The path to save the exported JSON file}
        {--api=default : The API to export a documentation for}
        {--pretty : Whether to export the JSON in a pretty-printed format}
    ';

    protected $description = 'Export the OpenAPI document to a JSON file.';

    public function handle(Generator $generator): void
    {
        $config = Scramble::getGeneratorConfig($api = $this->option('api'));

        // add optional 'pretty'
        $specification = json_encode($generator($config), $this->option('pretty') ? JSON_PRETTY_PRINT : 0);

        /** @var string $filename */
        $filename = $this->option('path') ?? $config->get('export_path', 'api'.($api === 'default' ? '' : "-$api").'.json');

        File::put($filename, $specification);

        $this->info("OpenAPI document exported to {$filename}.");
    }
}

usage:

$ php artisan scramble:export --pretty
$ cat api.json
{
    "openapi": "3.1.0",
    "info": {
        "title": "Laravel",
        "version": "0.0.1"
    },
    "servers": [
        {
            "url": "http:\/\/localhost\/api"
        }
    ]
}

[romalytvynenko]

@coffee-r Hey! Feel free to make a PR with pretty print being a default. No need in a flag, the single line output was never actually intended