Merge pull request #40 from matomo-org/PG-5170-plugin-cleanup

Prepare plugin for release, #PG-5170

Author: AltamashShaikh

.github/workflows/matomo-tests.yml

@@ -1,9 +1,9 @@
 # Action for running tests
 # This file has been automatically created.
 # To recreate it you can run this command
-# ./console generate:test-action --plugin="OpenApiDocs" --php-versions="7.2,8.4" --schedule-cron="0 19 * * 6"
+# ./console generate:test-action --plugin="ApiReference" --php-versions="7.2,8.4" --schedule-cron="0 19 * * 6"
 
-name: Plugin OpenApiDocs Tests
+name: Plugin ApiReference Tests
 
 on:
   pull_request:
@@ -49,7 +49,7 @@ jobs:
       - name: Run tests
         uses: matomo-org/github-action-tests@main
         with:
-          plugin-name: 'OpenApiDocs'
+          plugin-name: 'ApiReference'
           php-version: ${{ matrix.php }}
           test-type: 'PluginTests'
           matomo-test-branch: ${{ matrix.target }}

.github/workflows/phpcs.yml

@@ -30,7 +30,7 @@ jobs:
           tools: cs2pr
       - name: Install dependencies
         run:
-          composer init --name=matomo/openapidocs --quiet;
+          composer init --name=matomo/apireference --quiet;
           composer --no-plugins config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true -n;
           composer config repositories.matomo-coding-standards vcs https://github.com/matomo-org/matomo-coding-standards -n;
           composer require matomo-org/matomo-coding-standards:dev-master;

.github/workflows/phpstan.yml

@@ -15,7 +15,7 @@ permissions:
   statuses: read
 
 env:
-  PLUGIN_NAME: OpenApiDocs
+  PLUGIN_NAME: ApiReference
 
 jobs:
   phpstan:

API.php

@@ -7,26 +7,26 @@
  * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  */
 
-namespace Piwik\Plugins\OpenApiDocs;
+namespace Piwik\Plugins\ApiReference;
 
 use Piwik\Piwik;
-use Piwik\Plugins\OpenApiDocs\Generation\PluginListProvider;
+use Piwik\Plugins\ApiReference\Generation\PluginListProvider;
 use Piwik\Plugin\Manager;
-use Piwik\Plugins\OpenApiDocs\Specs\SpecGenerator;
-use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
+use Piwik\Plugins\ApiReference\Specs\SpecGenerator;
+use Piwik\Plugins\ApiReference\Specs\PathResolver;
 
 /**
  * Provides Reporting API endpoints for reading OpenAPI plugin configuration and specifications.
  *
  * Exposes endpoints to return the effective plugin list for spec generation, read pre-generated spec files,
  * or generate plugin OpenAPI specifications on demand.
  *
- * @method static \Piwik\Plugins\OpenApiDocs\API getInstance()
+ * @method static \Piwik\Plugins\ApiReference\API getInstance()
  */
 class API extends \Piwik\Plugin\API
 {
     /**
-     * Returns the plugin names used for OpenApiDocs spec generation.
+     * Returns the plugin names used for ApiReference spec generation.
      *
      * @return array<int, string>
      */
@@ -38,7 +38,7 @@ public function getAllowedPlugins(): array
     }
 
     /**
-     * Returns metadata for the plugins used by OpenApiDocs spec generation.
+     * Returns metadata for the plugins used by ApiReference spec generation.
      *
      * @return array<string, array{description: string}>
      */
@@ -74,7 +74,7 @@ public function getOpenApiSpec(string $pluginName, string $format = 'json'): arr
 
         $filePath = $this->getSpecFilePath($pluginName);
         if (!$this->isSpecFileReadable($filePath)) {
-            throw new \Exception('OpenAPI spec file was not found. Generate it first via openapidocs:generate-spec-file.');
+            throw new \Exception('OpenAPI spec file was not found. Generate it first via apireference:generate-spec-file.');
         }
 
         $specContents = $this->readSpecFile($filePath);

Annotations/AnnotationGenerator.php

@@ -9,12 +9,12 @@
 
 declare(strict_types=1);
 
-namespace Piwik\Plugins\OpenApiDocs\Annotations;
+namespace Piwik\Plugins\ApiReference\Annotations;
 
-use Matomo\Dependencies\OpenApiDocs\phpDocumentor\Reflection\DocBlock\Description;
-use Matomo\Dependencies\OpenApiDocs\phpDocumentor\Reflection\DocBlock\Tags\Param;
-use Matomo\Dependencies\OpenApiDocs\phpDocumentor\Reflection\DocBlock\Tags\TagWithType;
-use Matomo\Dependencies\OpenApiDocs\phpDocumentor\Reflection\DocBlockFactory;
+use Matomo\Dependencies\ApiReference\phpDocumentor\Reflection\DocBlock\Description;
+use Matomo\Dependencies\ApiReference\phpDocumentor\Reflection\DocBlock\Tags\Param;
+use Matomo\Dependencies\ApiReference\phpDocumentor\Reflection\DocBlock\Tags\TagWithType;
+use Matomo\Dependencies\ApiReference\phpDocumentor\Reflection\DocBlockFactory;
 use Piwik\Exception\PluginNotFoundException;
 use Piwik\API\DocumentationGenerator;
 use Piwik\API\NoDefaultValue;
@@ -23,9 +23,9 @@
 use Piwik\Http;
 use Piwik\Piwik;
 use Piwik\Plugin\Manager;
-use Piwik\Plugins\OpenApiDocs\Artifact\ArtifactWriter;
-use Piwik\Plugins\OpenApiDocs\OpenApiDocs;
-use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
+use Piwik\Plugins\ApiReference\Artifact\ArtifactWriter;
+use Piwik\Plugins\ApiReference\ApiReference;
+use Piwik\Plugins\ApiReference\Specs\PathResolver;
 use Piwik\SettingsPiwik;
 use Piwik\Url;
 use Piwik\UrlHelper;
@@ -116,7 +116,7 @@ public function __construct(
         $this->missingImportantDataWarnings = [];
         $this->allowLocalRequests = $allowLocalRequests;
         $this->parameterExamples = null;
-        $this->currentPluginDir = Manager::getInstance()::getPluginDirectory('OpenApiDocs');
+        $this->currentPluginDir = Manager::getInstance()::getPluginDirectory('ApiReference');
     }
 
     /**
@@ -136,7 +136,7 @@ public function generatePluginApiAnnotations(string $pluginName, bool $writeToFi
     {
         BaseValidator::check('plugin', $pluginName, [new NotEmpty()]);
 
-        if (in_array($pluginName, OpenApiDocs::PLUGIN_BLOCKLIST, true)) {
+        if (in_array($pluginName, ApiReference::PLUGIN_BLOCKLIST, true)) {
             throw new \RuntimeException('OpenAPI doc generation is blocked for ' . $pluginName . '.');
         }
 
@@ -224,7 +224,7 @@ public function getContentForGeneratedAnnotationsFile(array $annotations, string
         $lines = [
             '<?php',
             '',
-            'namespace Piwik\\Plugins\\OpenApiDocs\\tmp\\annotations;',
+            'namespace Piwik\\Plugins\\ApiReference\\tmp\\annotations;',
             '',
             '/**',
         ];
@@ -1089,7 +1089,7 @@ protected function getExampleIfAvailable(string $url, bool $useLocalToken = fals
         // If the flag to use a temp token is set, get a token and update the request URL
         $tempUrl = $url . '&hideIdSubDatable=1';
         if ($useLocalToken) {
-            $token = Piwik::requestTemporarySystemAuthToken('OpenApiDocs', 24);
+            $token = Piwik::requestTemporarySystemAuthToken('ApiReference', 24);
             $tempUrl = str_replace('&token_auth=anonymous', '&token_auth=' . $token, $tempUrl);
         }
         try {
@@ -1288,7 +1288,7 @@ public function convertExampleXmlToObject(string $xml): array
             // Handle any attributes
             $grouped = [];
             foreach ($node->attributes() as $attribute) {
-                $grouped[OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME][] = [$attribute->getName() => (string) $attribute];
+                $grouped[ApiReference::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME][] = [$attribute->getName() => (string) $attribute];
             }
 
             // Group children by tag name; repeated names become arrays
@@ -1476,7 +1476,7 @@ protected function buildMediaTypePropertiesArray(string $format, string $example
         $jsonSchema = $format === 'json' ? $this->buildSchemaAnnotationFromJsonExample($decodedExampleValue) : [];
         $xmlSchema = $format === 'xml' ? $this->buildSchemaAnnotationFromXmlExample($decodedExampleValue) : [];
         // If the XML example contains the temporary property to assist in building XML attributes in the schema, replace with newly encoded array with property removed
-        if ($format === 'xml' && strpos($exampleValue, OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME) !== false) {
+        if ($format === 'xml' && strpos($exampleValue, ApiReference::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME) !== false) {
             $exampleValue = json_encode($decodedExampleValue);
         }
 
@@ -1718,7 +1718,7 @@ public function buildSchemaAnnotationFromXmlExample(array &$xmlArrayObject, stri
     protected function removeTempOaXmlAttributeProperty(array &$decodedExampleValue): void
     {
         foreach ($decodedExampleValue as $key => &$value) {
-            if ($key === OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME) {
+            if ($key === ApiReference::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME) {
                 unset($decodedExampleValue[$key]);
                 // Add the attributes as actual properties so that they are visible in the example
                 foreach ($value as $attributeName => $attributeValue) {
@@ -1794,8 +1794,8 @@ public function buildPropertyAnnotationFromXmlExample(string $propName, array $v
                 $key = null;
                 foreach ($keys as $candidate) {
                     if (
-                        $candidate !== OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME
-                        && $candidate !== OpenApiDocs::OA_XML_ATTRIBUTES_DEFAULT_KEY_NAME
+                        $candidate !== ApiReference::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME
+                        && $candidate !== ApiReference::OA_XML_ATTRIBUTES_DEFAULT_KEY_NAME
                     ) {
                         $key = $candidate;
                         break;
@@ -1807,8 +1807,8 @@ public function buildPropertyAnnotationFromXmlExample(string $propName, array $v
 
             // Special handling for XML attributes (metadata-only)
             if (
-                $key === OpenApiDocs::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME
-                || $key === OpenApiDocs::OA_XML_ATTRIBUTES_DEFAULT_KEY_NAME
+                $key === ApiReference::OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME
+                || $key === ApiReference::OA_XML_ATTRIBUTES_DEFAULT_KEY_NAME
             ) {
                 $hasAttributes = true;
                 $childLines = array_merge($childLines, $this->buildXmlAttributeSchemaLines($value));

Annotations/ApiMethodInfoExtractor.php

@@ -9,14 +9,14 @@
 
 declare(strict_types=1);
 
-namespace Piwik\Plugins\OpenApiDocs\Annotations;
+namespace Piwik\Plugins\ApiReference\Annotations;
 
 use Piwik\Exception\PluginNotFoundException;
 use Piwik\API\Proxy;
 use Piwik\API\Request;
 use Piwik\Plugin\Manager;
-use Piwik\Plugins\OpenApiDocs\Artifact\ArtifactWriter;
-use Piwik\Plugins\OpenApiDocs\Specs\PathResolver;
+use Piwik\Plugins\ApiReference\Artifact\ArtifactWriter;
+use Piwik\Plugins\ApiReference\Specs\PathResolver;
 use Piwik\Validators\BaseValidator;
 use Piwik\Validators\NotEmpty;
 

Annotations/GlobalApiComponents.php

@@ -7,7 +7,7 @@
  * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  */
 
-namespace Piwik\Plugins\OpenApiDocs\Annotations;
+namespace Piwik\Plugins\ApiReference\Annotations;
 
 /**
  * Global components for generating OpenAPI specs for the Matomo Reporting API.

OpenApiDocs.php ApiReference.phpOpenApiDocs.php renamed to ApiReference.php

@@ -7,9 +7,9 @@
  * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
  */
 
-namespace Piwik\Plugins\OpenApiDocs;
+namespace Piwik\Plugins\ApiReference;
 
-class OpenApiDocs extends \Piwik\Plugin
+class ApiReference extends \Piwik\Plugin
 {
     public const DEFAULT_SPEC_VERSION = '1.0.0';
     public const OA_XML_ATTRIBUTES_TEMP_PROPERTY_NAME = 'oaXmlAttributes';
@@ -30,17 +30,17 @@ public function registerEvents()
     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';
+        $translationKeys[] = 'ApiReference_ReportingApiMoreInformation';
+        $translationKeys[] = 'ApiReference_ReportingApiReference';
+        $translationKeys[] = 'ApiReference_ReportingApiSummary';
+        $translationKeys[] = 'ApiReference_SwaggerApi';
+        $translationKeys[] = 'ApiReference_SwaggerPagePluginEmpty';
+        $translationKeys[] = 'ApiReference_SwaggerPageRequestFailed';
+        $translationKeys[] = 'ApiReference_SwaggerPageSpecLoadFailed';
+        $translationKeys[] = 'ApiReference_SwaggerPageSearchNoResults';
+        $translationKeys[] = 'ApiReference_SwaggerPageSearchPlaceholder';
+        $translationKeys[] = 'ApiReference_UserAuthentication';
+        $translationKeys[] = 'ApiReference_UserAuthenticationManageTokens';
+        $translationKeys[] = 'ApiReference_UserAuthenticationUsingTokenAuth';
     }
 }

Artifact/ArtifactWriter.php

@@ -9,7 +9,7 @@
 
 declare(strict_types=1);
 
-namespace Piwik\Plugins\OpenApiDocs\Artifact;
+namespace Piwik\Plugins\ApiReference\Artifact;
 
 use Piwik\Filesystem;
 

CHANGELOG.md

@@ -1,14 +1,3 @@
 ## Changelog
-
-5.0.2-b1 - 2026-03-16
-- Added support for string literal union types
-- Added API endpoint to retrieve static matomo swagger file
-- Added support for deactivated plugins
-- Removed token auth support
-
-5.0.1-b1 - 2026-02-16
-- Added class and function level docs
-- Updated spec generation command to allow single swagger file generation
-
-5.0.0-b1
-- Initial implementation of plugin and POC generating documentation from annotations
+5.0.0
+- Initial release of ApiReference plugin