GenerateSpecFile.php

<?php

/**
 * Matomo - free/libre analytics platform
 *
 * @link    https://matomo.org
 * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
 */

namespace Piwik\Plugins\OpenApiDocs\Commands;

use Piwik\Container\StaticContainer;
use Piwik\Plugin\ConsoleCommand;
use Piwik\Plugins\OpenApiDocs\Generation\SpecGenerationService;
use Piwik\Plugins\OpenApiDocs\OpenApiDocs;
use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;

/**
 * This class lets you define a new command. To read more about commands have a look at our Matomo Console guide on
 * https://developer.matomo.org/guides/piwik-on-the-command-line
 *
 * As Matomo Console is based on the Symfony Console you might also want to have a look at
 * https://symfony.com/doc/current/components/console/index.html
 */
class GenerateSpecFile extends ConsoleCommand
{
    /**
     * @var SpecGenerationService
     */
    private $specGenerationService;

    /**
     * @var PathResolver
     */
    private $specPathResolver;

    public function __construct(?SpecGenerationService $specGenerationService = null, ?PathResolver $specPathResolver = null)
    {
        $this->specGenerationService = $specGenerationService ?: StaticContainer::get(SpecGenerationService::class);
        $this->specPathResolver = $specPathResolver ?: StaticContainer::get(PathResolver::class);

        parent::__construct();
    }

    /**
     * This method allows you to configure your command. Here you can define the name and description of your command
     * as well as all options and arguments you expect when executing it.
     */
    protected function configure()
    {
        $this->setName('openapidocs:generate-spec-file');
        $this->setDescription('Generate the OpenAPI documentation file for the Matomo APIs.');
        $this->addRequiredValueOption('plugin', 'p', 'Name of the plugin to document. Multiple plugins can be comma-separated');
        $this->addRequiredValueOption('format', 'f', 'Format of the spec file (JSON or YAML). Default is JSON');
        $this->addRequiredValueOption('api-version', null, 'Version of the spec file. Default is 1.0.0');
        $this->addNoValueOption('not-dry-run', null, 'Flag to allow writing to file instead of outputting a dry run.');
        $this->addNoValueOption('add-annotations', null, 'Flag to also generate annotations that are required to generate OpenAPI documentation');
    }

    /**
     * Interact with the user.
     *
     * This method is executed before the InputDefinition is validated.
     * This means that this is the only place where the command can
     * interactively ask for values of missing required arguments.
     */
    protected function doInteract(): void
    {
    }

    /**
     * Initializes the command after the input has been bound and before the input
     * is validated.
     *
     * This is mainly useful when a lot of commands extends one main command
     * where some things need to be initialized based on the input arguments and options.
     */
    protected function doInitialize(): void
    {
    }

    /**
     * The actual task is defined in this method. Here you can access any option or argument that was defined on the
     * command line via $this->getInput() and write anything to the console via $this->getOutput().
     * In case anything went wrong during the execution you should throw an exception to make sure the user will get a
     * useful error message and to make sure the command does not exit with the status code 0.
     *
     * Ideally, the actual command is quite short as it acts like a controller. It should only receive the input values,
     * execute the task by calling a method of another class and output any useful information.
     *
     * Execute the command like: ./console openapidocs:generate-spec-file --plugin=TagManager --not-dry-run
     */
    protected function doExecute(): int
    {
        $input = $this->getInput();
        $output = $this->getOutput();

        $plugin = $input->getOption('plugin');

        if (empty($plugin)) {
            throw new \RuntimeException('Please specify a plugin name.');
        }

        $pluginNames = array_values(array_filter(array_map('trim', explode(',', $plugin)), static function (string $pluginName): bool {
            return $pluginName !== '';
        }));
        $format = $input->getOption('format') ?: 'json';
        $version = $input->getOption('api-version') ?: OpenApiDocs::DEFAULT_SPEC_VERSION;
        $notDryRun = $input->getOption('not-dry-run') ?: false;
        $addAnnotations = $input->getOption('add-annotations') ?: false;

        $message = sprintf('<info>Generating documentation for: %s</info>', $plugin);

        $output->writeln($message);

        $result = $this->specGenerationService->generateSpecForPlugins(
            $plugin,
            $format,
            $version,
            $notDryRun,
            $addAnnotations
        );

        if ($addAnnotations) {
            foreach ($pluginNames as $pluginName) {
                $output->writeln('<info>Created Annotations for ' . $pluginName . ' and wrote results to ' . $this->specPathResolver->getAnnotationsDirectory() . '</info>');
            }
        }

        if ($notDryRun) {
            $output->writeln('<info>Results written to ' . $this->specPathResolver->getSpecDirectory() . '</info>');
            return self::SUCCESS;
        }

        $output->writeln($result);

        return self::SUCCESS;
    }
}