From 8fb96ba6a564a3c0886eb9eb3ce7d5fb418003db Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Tue, 26 May 2026 12:17:56 +1200 Subject: [PATCH 1/2] Now redirecting to new API page, added link to old reference on swagger pages, updated script to use ApiReference instead of OpenApiDocs --- app/helpers/OpenApiSpecRegistry.php | 7 +++--- app/helpers/Redirects.php | 2 ++ app/public/css/swagger-ui-overrides.css | 4 +++ app/routes/page.php | 26 +++++++++++++++++++ app/templates/api-legacy-redirect.twig | 33 +++++++++++++++++++++++++ app/templates/api-swagger-index.twig | 2 +- app/templates/api-swagger.twig | 1 + fetch-openapi-specs.php | 6 ++--- 8 files changed, 74 insertions(+), 7 deletions(-) create mode 100644 app/templates/api-legacy-redirect.twig diff --git a/app/helpers/OpenApiSpecRegistry.php b/app/helpers/OpenApiSpecRegistry.php index d475af0b1..1e51a10e4 100644 --- a/app/helpers/OpenApiSpecRegistry.php +++ b/app/helpers/OpenApiSpecRegistry.php @@ -25,7 +25,7 @@ public static function getPluginMetadataPath() } /** - * @return array + * @return array */ public static function getPluginSpecs() { @@ -50,6 +50,7 @@ public static function getPluginSpecs() $name = $matches[1]; $specs[] = [ 'name' => self::splitCamelCase($name), + 'pluginName' => $name, 'slug' => self::toSlug($name), 'file' => $basename, 'url' => '/openapi/' . $basename, @@ -66,7 +67,7 @@ public static function getPluginSpecs() /** * @param string $slug - * @return array{name: string, slug: string, file: string, url: string, summary: string}|null + * @return array{name: string, pluginName: string, slug: string, file: string, url: string, summary: string}|null */ public static function getPluginSpecBySlug($slug) { @@ -81,7 +82,7 @@ public static function getPluginSpecBySlug($slug) /** * @param string $slug - * @return array{pluginSpec: array{name: string, slug: string, file: string, url: string, summary: string}, pluginSpecData: array}|null + * @return array{pluginSpec: array{name: string, pluginName: string, slug: string, file: string, url: string, summary: string}, pluginSpecData: array}|null */ public static function getPluginSpecDocumentBySlug($slug) { diff --git a/app/helpers/Redirects.php b/app/helpers/Redirects.php index 7de8a995f..d211c2d92 100644 --- a/app/helpers/Redirects.php +++ b/app/helpers/Redirects.php @@ -19,6 +19,8 @@ public static function getRedirects() '/api-reference/PHP-Piwik-Tracker/' => '/api-reference/PHP-Matomo-Tracker/', '/api-reference/php-piwik-tracker/' => '/api-reference/PHP-Matomo-Tracker/', '/api-reference/php-piwik-tracker' => '/api-reference/PHP-Matomo-Tracker/', + '/api-reference/reporting-api/' => '/api-reference/reporting-api', + '/api-reference/reporting-api-legacy/' => '/api-reference/reporting-api-legacy', '/contributing' => '/guides/contributing-to-piwik-core', '/plugins' => '/develop', '/core' => '/piwik-in-depth', diff --git a/app/public/css/swagger-ui-overrides.css b/app/public/css/swagger-ui-overrides.css index 3c733f2c2..508df2367 100644 --- a/app/public/css/swagger-ui-overrides.css +++ b/app/public/css/swagger-ui-overrides.css @@ -203,3 +203,7 @@ word-break: normal; word-wrap: normal; } + +#swagger-ui + .old-api-docs-paragraph { + margin-top: 18px; +} diff --git a/app/routes/page.php b/app/routes/page.php index ffd04c58e..9303220da 100644 --- a/app/routes/page.php +++ b/app/routes/page.php @@ -119,6 +119,32 @@ function renderGuide(Slim\Views\Twig $view, Response $response, Psr\Http\Message ]); }); +$app->get('/api-reference/reporting-api', function (Request $request, Response $response, $args) { + $category = new ApiReferenceCategory(); + $guide = new ApiReferenceGuide('api'); + + return $this->get("view")->render($response, 'api-legacy-redirect.twig', [ + 'category' => $category, + 'guide' => $guide, + 'linkToEditDocument' => $guide->linkToEdit(), + 'activeMenu' => $category->getName(), + 'currentPath' => $request->getUri()->getPath(), + 'selectedPiwikVersion' => Environment::getPiwikVersion(), + 'urlIfAvailableInNewerVersion' => (Environment::isLatestPiwikVersion() ? false : Url::getUrlIfDocumentIsAvailableInPiwikVersion($request->getUri()->getPath(), LATEST_PIWIK_DOCS_VERSION)), + 'pluginSpecs' => OpenApiSpecRegistry::getPluginSpecs(), + ]); +}); + +$app->get('/api-reference/reporting-api-legacy', function (Request $request, Response $response, $args) { + return renderGuide( + $this->get("view"), + $response, + $request->getUri(), + new ApiReferenceGuide('reporting-api'), + new ApiReferenceCategory() + ); +}); + $app->get('/api-reference/api/{plugin}', function (Request $request, Response $response, $args) { $pluginSpecs = OpenApiSpecRegistry::getPluginSpecs(); $pluginSpecDocument = OpenApiSpecRegistry::getPluginSpecDocumentBySlug($args['plugin']); diff --git a/app/templates/api-legacy-redirect.twig b/app/templates/api-legacy-redirect.twig new file mode 100644 index 000000000..261b013e8 --- /dev/null +++ b/app/templates/api-legacy-redirect.twig @@ -0,0 +1,33 @@ +{% extends 'guide.twig' %} + +{% set title = 'API Reference' %} + +{% block meta %} + + +{% endblock %} + +{% block guideContent %} +

Redirecting to the new API documentation.

+

Continue to the API reference

+{% endblock %} diff --git a/app/templates/api-swagger-index.twig b/app/templates/api-swagger-index.twig index d39ddeb7e..606795533 100644 --- a/app/templates/api-swagger-index.twig +++ b/app/templates/api-swagger-index.twig @@ -16,7 +16,7 @@ {% endfor %} -

Looking for the legacy API reference? The legacy API reference page is still available while we continue improving the new API documentation. If anything is missing or behaving unexpectedly in this new version, please let us know so we can improve the experience.

+

Looking for the legacy API reference? The legacy API reference page is still available. Old reporting API links now redirect here. If anything is missing or behaving unexpectedly in this new version, please let us know so we can improve the experience.

{% endif %} {% endblock %} diff --git a/app/templates/api-swagger.twig b/app/templates/api-swagger.twig index e0c90bdf0..05d8bd297 100644 --- a/app/templates/api-swagger.twig +++ b/app/templates/api-swagger.twig @@ -12,6 +12,7 @@ Test API requests use our public demo environment. Because of this, read requests work but requests that create, edit, or delete data do not.
+

Looking for the legacy API reference? The legacy API reference page is still available. Old reporting API links now redirect here. If anything is missing or behaving unexpectedly in this new version, please let us know so we can improve the experience.

{% endblock %} {% block footer %} diff --git a/fetch-openapi-specs.php b/fetch-openapi-specs.php index 0d876dcbc..f0f4a4283 100644 --- a/fetch-openapi-specs.php +++ b/fetch-openapi-specs.php @@ -145,7 +145,7 @@ function fetchJson(string $baseUrl, string $tokenAuth, array $params): array try { $plugins = fetchJson($baseUrl, $tokenAuth, [ - 'method' => 'OpenApiDocs.getAllowedPlugins', + 'method' => 'ApiReference.getAllowedPlugins', ]); } catch (Throwable $e) { fwrite(STDERR, "Failed to fetch plugin whitelist: {$e->getMessage()}\n"); @@ -154,7 +154,7 @@ function fetchJson(string $baseUrl, string $tokenAuth, array $params): array try { $pluginMetadata = fetchJson($baseUrl, $tokenAuth, [ - 'method' => 'OpenApiDocs.getAllowedPluginMetadata', + 'method' => 'ApiReference.getAllowedPluginMetadata', ]); } catch (Throwable $e) { fwrite(STDERR, "Failed to fetch plugin metadata: {$e->getMessage()}\n"); @@ -181,7 +181,7 @@ function fetchJson(string $baseUrl, string $tokenAuth, array $params): array try { $spec = fetchJson($baseUrl, $tokenAuth, [ - 'method' => 'OpenApiDocs.getGeneratedOpenApiSpec', + 'method' => 'ApiReference.getGeneratedOpenApiSpec', 'plugin' => $plugin, ]); From c2853b458850e774c3a7171bc36c19a82ac618de Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Tue, 26 May 2026 16:15:28 +1200 Subject: [PATCH 2/2] Add proper redirects --- app/templates/api-legacy-redirect.twig | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/app/templates/api-legacy-redirect.twig b/app/templates/api-legacy-redirect.twig index 261b013e8..279fed19a 100644 --- a/app/templates/api-legacy-redirect.twig +++ b/app/templates/api-legacy-redirect.twig @@ -9,6 +9,7 @@