IBX-6107: REST API ref tester

tools/raml2html/README.md

@@ -4,15 +4,35 @@ Tool for generating static HTML from RAML definitions.
 
 ## Installation
 
-Install required dependencies before use. Go to raml2html root directory and run:
+PHP 7.4 and [Composer](https://getcomposer.org/) are required.
 
-```
-composer install
+To install required dependencies, go to raml2html directory and run:
+
+```sh
+composer install;
 ``` 
 
-To generate static HTML from RAML definitions, use the following code:
+## Usage
+
+To generate static HTML from RAML definitions, use the following code from project root:
+
+```sh
+php tools/raml2html/raml2html.php build --non-standard-http-methods=COPY,MOVE,PUBLISH,SWAP -t default -o docs/api/rest_api/rest_api_reference/output/ docs/api/rest_api/rest_api_reference/input/ez.raml
+```
 
+To test static HTML against an Ibexa DXP to find route removed and missing routes:
 
 ```sh
-php tools/raml2html/raml2html.php build --non-standard-http-methods=COPY,MOVE,PUBLISH,SWAP -t default -o docs/api/rest_api_reference/output/ docs/api/rest_api_reference/input/ez.raml
+php tools/raml2html/raml2html.php test docs/api/rest_api/rest_api_reference/rest_api_reference.html ~/ibexa-dxp
+```
+
+Note: The Ibexa DXP doesn't need to run.
+
+```shell
+mkdir ~/ibexa-dxp;
+cd ~/ibexa-dxp;
+composer create-project ibexa/commerce-skeleton . --no-install --ignore-platform-reqs --no-scripts;
+composer install --ignore-platform-reqs --no-scripts;
+cd -;
+php tools/raml2html/raml2html.php test docs/api/rest_api/rest_api_reference/rest_api_reference.html ~/ibexa-dxp
 ```

tools/raml2html/composer.json

@@ -16,6 +16,10 @@
     ],
     "require": {
         "php": "^7.4",
+        "ext-json": "*",
+        "ext-yaml": "*",
+        "ext-dom": "*",
+        "ext-libxml": "*",
         "symfony/console": "^4.2",
         "raml-org/raml-php-parser": "dev-master",
         "twig/twig": "^2.0",

tools/raml2html/src/Application.php

@@ -7,6 +7,7 @@
 use EzSystems\Raml2Html\Command\BuildCommand;
 use EzSystems\Raml2Html\Command\ClearCacheCommand;
 use EzSystems\Raml2Html\Command\LintTypesCommand;
+use EzSystems\Raml2Html\Command\TestCommand;
 use EzSystems\Raml2Html\Generator\Generator;
 use EzSystems\Raml2Html\RAML\ParserFactory;
 use EzSystems\Raml2Html\Twig\Extension\HashExtension;
@@ -39,6 +40,7 @@ protected function getDefaultCommands(): array
                 $this->getRamlParserFactory()
             ),
             new ClearCacheCommand(self::CACHE_DIR),
+            new TestCommand(),
         ]);
     }
 

tools/raml2html/src/Command/TestCommand.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace EzSystems\Raml2Html\Command;
+
+use EzSystems\Raml2Html\Test\ReferenceTester;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+final class TestCommand extends Command
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function configure(): void
+    {
+        $this->setName('test')
+            ->setDescription('Compare REST API Reference documentation with Ibexa DXP routing configuration under /api/ibexa/v2 prefix')
+            ->setHelp('It is recommended to not use --console-path and --routing-file options while testing the Rest API Reference HTML file against configuration. Those options are used to test that the default configuration file list is up-to-date and other subtleties.')
+            ->addArgument('rest-api-reference', InputArgument::REQUIRED, 'Path to the REST API Reference HTML file')
+            ->addArgument('ibexa-dxp-root', InputArgument::REQUIRED, 'Path to an Ibexa DXP root directory')
+            ->addOption('console-path', 'c', InputOption::VALUE_OPTIONAL, 'Path to the console relative to Ibexa DXP root directory (if no value, use `bin/console`)', false)
+            ->addOption('routing-file', 'f', InputOption::VALUE_IS_ARRAY | InputOption::VALUE_OPTIONAL, 'Path to a routing configuration YAML file relative to Ibexa DXP root directory', ReferenceTester::DEFAULT_FILE_LIST)
+            ->addOption('tested-routes', 't', InputOption::VALUE_OPTIONAL,
+                "ref: Test if reference routes are found in the configuration file;\n
+                            conf: Test if configuration routes are found in the reference file;\n
+                            both: Test both.", 'both');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $restApiReference = $input->getArgument('rest-api-reference');
+        if (!is_file($restApiReference)) {
+            $output->writeln("<error>$restApiReference doesn't exist or is not a file.</error>");
+            return 1;
+        }
+
+        $dxpRoot = $input->getArgument('ibexa-dxp-root');
+        if (!is_dir($dxpRoot)) {
+            $output->writeln("<error>$dxpRoot doesn't exist or is not a directory.</error>");
+            return 2;
+        }
+
+        $consolePath = $input->getOption('console-path');
+        if (null === $consolePath) {
+            $consolePath = 'bin/console';
+        }
+
+        $routingFiles = $input->getOption('routing-file');
+
+        $referenceTester = new ReferenceTester($restApiReference, $dxpRoot, $consolePath, $routingFiles, $output);
+
+        $testedRoutes = [
+            'ref' => ReferenceTester::TEST_REFERENCE_ROUTES,
+            'conf' => ReferenceTester::TEST_CONFIG_ROUTES,
+            'both' => ReferenceTester::TEST_ALL_ROUTES,
+        ][$input->getOption('tested-routes')] ?? ReferenceTester::TEST_ALL_ROUTES;
+
+        $referenceTester->run($testedRoutes);
+
+        return 0;
+    }
+}