Frontend API documentation, #PG-5031

.gitignore

@@ -13,6 +13,7 @@ vendor/**/composer.lock
 /vue/dist/*.common.js
 /vue/dist/*.map
 /vue/dist/*.development.*
+/vue/node_modules/
 /tmp/specs/*
 !/tmp/specs/.gitkeep
 /tmp/annotations/*

Annotations/AnnotationGenerator.php

@@ -964,8 +964,8 @@ protected function getExampleIfAvailable(string $url, bool $useLocalToken = fals
                 $httpMethod = 'GET'
             );
         } catch (\Throwable $e) {
-            // Add a little bit more context for troubleshooting the failed request
-            throw new \Exception('Error getting example from URL: ' . $url . PHP_EOL . $e, 0, $e);
+            // Example lookups are best-effort. Timeouts and other transport failures should not abort spec generation.
+            return '';
         }
 
         // If the example didn't load or resulted in an error, simply return an empty string

Controller.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\OpenApiDocs;
+
+use Piwik\Piwik;
+use Piwik\View;
+
+class Controller extends \Piwik\Plugin\ControllerAdmin
+{
+    public function swagger(): string
+    {
+        Piwik::checkUserHasSomeViewAccess();
+
+        $view = new View('@OpenApiDocs/swagger');
+        $this->setBasicVariablesView($view);
+
+        return $view->render();
+    }
+}

Menu.php

@@ -0,0 +1,29 @@
+<?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;
+
+use Piwik\Menu\MenuAdmin;
+use Piwik\Piwik;
+
+class Menu extends \Piwik\Plugin\Menu
+{
+    public function configureAdminMenu(MenuAdmin $menu): void
+    {
+        if (!Piwik::isUserHasSomeViewAccess()) {
+            return;
+        }
+
+        $menu->addPlatformItem(
+            'OpenApiDocs_SwaggerApi',
+            $this->urlForAction('swagger'),
+            30
+        );
+    }
+}

OpenApiDocs.php

@@ -22,6 +22,25 @@ class OpenApiDocs extends \Piwik\Plugin
 
     public function registerEvents()
     {
-        return [];
+        return [
+            'Translate.getClientSideTranslationKeys' => 'getClientSideTranslationKeys',
+        ];
+    }
+
+    public function getClientSideTranslationKeys(&$translationKeys): void
+    {
+        $translationKeys[] = 'CoreHome_LearnMoreFullStop';
+        $translationKeys[] = 'OpenApiDocs_ReportingApiMoreInformation';
+        $translationKeys[] = 'OpenApiDocs_ReportingApiReference';
+        $translationKeys[] = 'OpenApiDocs_ReportingApiSummary';
+        $translationKeys[] = 'OpenApiDocs_SwaggerApi';
+        $translationKeys[] = 'OpenApiDocs_SwaggerPagePluginEmpty';
+        $translationKeys[] = 'OpenApiDocs_SwaggerPageRequestFailed';
+        $translationKeys[] = 'OpenApiDocs_SwaggerPageSpecLoadFailed';
+        $translationKeys[] = 'OpenApiDocs_SwaggerPageSearchNoResults';
+        $translationKeys[] = 'OpenApiDocs_SwaggerPageSearchPlaceholder';
+        $translationKeys[] = 'OpenApiDocs_UserAuthentication';
+        $translationKeys[] = 'OpenApiDocs_UserAuthenticationManageTokens';
+        $translationKeys[] = 'OpenApiDocs_UserAuthenticationUsingTokenAuth';
     }
 }

README.md

@@ -4,6 +4,16 @@
 
 Allow generating OpenAPI documentation for the Matomo public APIs.
 
+## Frontend assets
+Swagger UI is managed via npm inside [vue/package.json](/vue/package.json). The plugin runtime does not load Swagger UI from `node_modules`; instead, the needed distributable files are synced into `vue/lib/swagger-ui/`.
+
+Typical workflow:
+- Run `npm install` in `plugins/OpenApiDocs/vue`.
+- Run `npm run sync-swagger-ui` in `plugins/OpenApiDocs/vue` after adding or updating `swagger-ui-dist`.
+- Run `ddev matomo:console vue:build OpenApiDocs` after changing Vue source.
+
+The plugin-specific Swagger overrides live in [vue/src/SwaggerPage/swagger-ui-overrides.css](/vue/src/SwaggerPage/swagger-ui-overrides.css).
+
 ## Dependencies
 This plugin had its vendored dependencies scoped using [matomo scoper](https://github.com/matomo-org/matomo-scoper). This means that composer packages are prefixed so that they won't conflict with the same libraries used by other plugins.
 If you need to update a dependency, you should be able to run `composer install` to populate the vendor directory and then follow the [instructions for scoping a plugin](https://github.com/matomo-org/matomo-scoper#how-to-scope-a-matomo-plugin). Since the scoper.inc.php file already exists, it will hopefully be as simple as running the scoper for this plugin. Once that's done, you'll also need to make some of the dependencies compatible with Matomo's minimum supported version of PHP.
@@ -30,4 +40,4 @@ return static function (RectorConfig $rectorConfig): void {
 ```
 With all that in place, you should be able to run Rector like so: `vendor/bin/rector process {path_to_this_plugin/vendor/prefixed} --config={path_to_config_file}`
 
-> **_NOTE:_**  For Matomo developers, there's an internal DevPluginCommands plugin with a command that handles scoping and running Rector. See the SearchEngineKeywordsPerformance plugin's README.md for more details.
+> **_NOTE:_**  For Matomo developers, there's an internal DevPluginCommands plugin with a command that handles scoping and running Rector. See the SearchEngineKeywordsPerformance plugin's README.md for more details.

lang/en.json

@@ -0,0 +1,16 @@
+{
+    "OpenApiDocs": {
+        "ReportingApiMoreInformation": "More info about the Matomo APIs available in %1$sIntroduction to Matomo API%2$s and the %3$sMatomo API Reference%4$s.",
+        "ReportingApiReference": "Reporting API Reference",
+        "ReportingApiSummary": "All the data in Matomo is available through simple APIs.",
+        "SwaggerApi": "Swagger API",
+        "SwaggerPagePluginEmpty": "No plugins are configured in the OpenApiDocs whitelist.",
+        "SwaggerPageRequestFailed": "The plugin whitelist could not be loaded.",
+        "SwaggerPageSpecLoadFailed": "The OpenAPI spec could not be loaded for this plugin.",
+        "SwaggerPageSearchNoResults": "No plugins match your search.",
+        "SwaggerPageSearchPlaceholder": "Search by plugin name",
+        "UserAuthentication": "User authentication",
+        "UserAuthenticationManageTokens": "You can manage your authentication tokens on your security page.",
+        "UserAuthenticationUsingTokenAuth": "If you want to request data within a script, a crontab, etc. you need to add the '%3$s' URL parameter to the API calls for URLs that require authentication."
+    }
+}

templates/swagger.twig

@@ -0,0 +1,17 @@
+{% extends 'admin.twig' %}
+
+{% block head %}
+    {{ parent() }}
+    <link rel="stylesheet" href="plugins/OpenApiDocs/vue/lib/swagger-ui/swagger-ui.css" />
+    <link rel="stylesheet" href="plugins/OpenApiDocs/vue/src/SwaggerPage/swagger-ui-overrides.css" />
+    <script src="plugins/OpenApiDocs/vue/lib/swagger-ui/swagger-ui-bundle.js"></script>
+{% endblock %}
+
+{% set title %}{{ 'OpenApiDocs_SwaggerApi'|translate }}{% endset %}
+
+{% block content %}
+    <div
+        vue-entry="OpenApiDocs.SwaggerPage"
+        piwik-url="{{ piwikUrl|default(null)|json_encode }}"
+    ></div>
+{% endblock %}

tests/Integration/ControllerTest.php

@@ -0,0 +1,115 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\OpenApiDocs\tests\Integration;
+
+use Piwik\Access;
+use Piwik\Container\StaticContainer;
+use Piwik\Plugin\Manager;
+use Piwik\Plugins\OpenApiDocs\Controller;
+use Piwik\Tests\Framework\Fixture;
+use Piwik\Tests\Framework\Mock\FakeAccess;
+use Piwik\Tests\Framework\TestCase\IntegrationTestCase;
+
+/**
+ * @group OpenApiDocs
+ * @group ControllerTest
+ * @group Plugins
+ */
+class ControllerTest extends IntegrationTestCase
+{
+    /**
+     * @var Controller
+     */
+    private $controller;
+
+    /**
+     * @var array<string, mixed>
+     */
+    private $backupGet;
+
+    /**
+     * @var array<string, mixed>
+     */
+    private $backupRequest;
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->backupGet = $_GET;
+        $this->backupRequest = $_REQUEST;
+
+        Fixture::createSuperUser();
+        if (!Fixture::siteCreated(1)) {
+            Fixture::createWebsite('2012-01-01 00:00:00');
+        }
+
+        Fixture::resetTranslations();
+        Fixture::loadAllTranslations();
+
+        Manager::getInstance()->loadPlugin('OpenApiDocs');
+
+        $_GET = [
+            'idSite' => 1,
+            'period' => 'day',
+            'date' => 'today',
+        ];
+        $_REQUEST = $_GET;
+
+        $this->controller = new Controller();
+    }
+
+    public function tearDown(): void
+    {
+        $_GET = $this->backupGet;
+        $_REQUEST = $this->backupRequest;
+
+        Fixture::resetTranslations();
+
+        parent::tearDown();
+    }
+
+    public function testSwaggerRendersAdminPageForViewAccess(): void
+    {
+        FakeAccess::clearAccess(
+            $superUser = false,
+            $idSitesAdmin = [0],
+            $idSitesView = [1],
+            $identity = 'viewAccessUser'
+        );
+
+        $html = $this->controller->swagger();
+
+        $this->assertNotSame('', $html);
+        $this->assertStringContainsString('vue-entry="OpenApiDocs.SwaggerPage"', $html);
+        $this->assertStringContainsString('piwik-url=', $html);
+        $this->assertStringContainsString('plugins/OpenApiDocs/vue/lib/swagger-ui/swagger-ui.css', $html);
+        $this->assertStringContainsString('plugins/OpenApiDocs/vue/src/SwaggerPage/swagger-ui-overrides.css', $html);
+        $this->assertStringContainsString('plugins/OpenApiDocs/vue/lib/swagger-ui/swagger-ui-bundle.js', $html);
+        $this->assertStringContainsString('Swagger', $html);
+    }
+
+    public function testSwaggerThrowsWhenUserHasNoAccess(): void
+    {
+        $originalAccess = StaticContainer::getContainer()->get(Access::class);
+        StaticContainer::getContainer()->set(Access::class, new FakeAccess(false, [], [], 'noAccess'));
+
+        try {
+            $this->expectException(\Exception::class);
+            $this->expectExceptionMessage('checkUserHasSomeViewAccess');
+
+            $this->controller->swagger();
+        } finally {
+            StaticContainer::getContainer()->set(Access::class, $originalAccess);
+        }
+    }
+}

tests/Integration/MenuTest.php

@@ -0,0 +1,92 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\OpenApiDocs\tests\Integration;
+
+use Piwik\Cache;
+use Piwik\Menu\MenuAdmin;
+use Piwik\Plugin\Manager;
+use Piwik\Tests\Framework\Fixture;
+use Piwik\Tests\Framework\Mock\FakeAccess;
+use Piwik\Tests\Framework\TestCase\IntegrationTestCase;
+
+/**
+ * @group OpenApiDocs
+ * @group MenuTest
+ * @group Plugins
+ */
+class MenuTest extends IntegrationTestCase
+{
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        Fixture::createSuperUser();
+        if (!Fixture::siteCreated(1)) {
+            Fixture::createWebsite('2012-01-01 00:00:00');
+        }
+
+        Manager::getInstance()->loadPlugin('OpenApiDocs');
+    }
+
+    public function provideContainerConfig(): array
+    {
+        return ['Piwik\Access' => new FakeAccess()];
+    }
+
+    public function tearDown(): void
+    {
+        Cache::getTransientCache()->flushAll();
+        MenuAdmin::unsetInstance();
+
+        parent::tearDown();
+    }
+
+    public function testConfigureAdminMenuAddsSwaggerItemForViewAccess(): void
+    {
+        FakeAccess::clearAccess(
+            $superUser = false,
+            $idSitesAdmin = [0],
+            $idSitesView = [1],
+            $identity = 'viewAccessUser'
+        );
+
+        $items = $this->buildConfiguredMenu()->getMenu();
+
+        $this->assertArrayHasKey('CorePluginsAdmin_MenuPlatform', $items);
+        $this->assertArrayHasKey('OpenApiDocs_SwaggerApi', $items['CorePluginsAdmin_MenuPlatform']);
+    }
+
+    public function testConfigureAdminMenuSkipsSwaggerItemWithoutViewAccess(): void
+    {
+        FakeAccess::clearAccess(
+            $superUser = false,
+            $idSitesAdmin = [],
+            $idSitesView = [],
+            $identity = 'noAccessUser'
+        );
+
+        $items = $this->buildConfiguredMenu()->getMenu();
+
+        if (!isset($items['CorePluginsAdmin_MenuPlatform'])) {
+            $this->assertArrayNotHasKey('CorePluginsAdmin_MenuPlatform', $items);
+            return;
+        }
+
+        $this->assertArrayNotHasKey('OpenApiDocs_SwaggerApi', $items['CorePluginsAdmin_MenuPlatform']);
+    }
+
+    private function buildConfiguredMenu(): MenuAdmin
+    {
+        MenuAdmin::unsetInstance();
+        return MenuAdmin::getInstance();
+    }
+}

tests/Unit/APITest.php

@@ -102,7 +102,7 @@ public function testGetOpenApiSpecThrowsExceptionWhenFormatIsInvalid()
         $api = $this->buildApiMock('/tmp/CustomAlerts_openapi_spec_v1.0.0.json', true, '{}');
 
         $this->expectException(\Exception::class);
-        $this->expectExceptionMessage('General_ExceptionInvalidReportRendererFormat');
+        $this->expectExceptionMessage("Report format 'yaml' not valid");
 
         $api->getOpenApiSpec('CustomAlerts', 'yaml');
     }