Merge branch '5.x-dev' into PG-5206-ui-tests

Author: lachiebol

Annotations/AnnotationGenerator.php

@@ -933,7 +933,7 @@ protected function getApplicableDemoExampleUrls(string $pluginName, string $meth
         ];
 
         // Don't build example URLs for anything that isn't the R in CRUD. E.g. No create, update, or delete.
-        $notAllowedExampleUrlOperations = ['create', 'add', 'save', 'set', 'update', 'delete', 'remove', 'copy', 'duplicate'];
+        $notAllowedExampleUrlOperations = ['create', 'add', 'save', 'set', 'update', 'delete', 'remove', 'copy', 'duplicate', 'generate'];
         foreach ($notAllowedExampleUrlOperations as $operation) {
             if (stripos($methodName, $operation) === 0) {
                 return [];

CHANGELOG.md

@@ -1,3 +1,9 @@
 ## Changelog
+5.0.2 - 25/05/2026
+- Updated FAQ
+
+5.0.1 - 25/05/2026
+- Added fix for endpoints that don't return valid API responses
+
 5.0.0
 - Initial release of ApiReference plugin

README.md

@@ -2,12 +2,13 @@
 
 ## Description
 
+The API Reference plugin generates an OpenAPI (Swagger) specification from Matomo API definitions and supported plugin metadata. 
+
 As APIs and plugins expose additional metadata, developers can browse available API endpoints, explore request parameters and response formats, and test API requests directly from the documentation interface.
 
 ### Features include:
 
 * Interactive Swagger/OpenAPI-based API documentation
-* Searchable API methods and endpoints
 * Request and response schema documentation
 * Parameter descriptions and example requests
 * Improved navigation and API discoverability

docs/faq.md

@@ -0,0 +1,39 @@
+## FAQ
+
+__Why is the OpenAPI specification file not generated?__
+
+This can happen if the API Reference plugin is disabled, the Matomo cache has not been cleared, or the API specification generation process encountered an error.
+
+Try the following:
+
+* Ensure the API Reference plugin is installed and activated.
+* Clear the Matomo cache.
+* Check your server logs for PHP or permission errors.
+* Verify that the Matomo instance can write generated files to the configured directory.
+* Ensure all required plugins and dependencies are enabled.
+
+The specification files are generated daily using a scheduled Matomo task. To check when this task is scheduled to run next, use the TasksTimetable plugin.
+
+You can manually generate the specification files using the following command:
+
+```bash
+core:run-scheduled-tasks "Piwik\Plugins\ApiReference\Tasks.generateConfiguredPluginSpecs"
+```
+
+The initial generation process may take some time to complete, depending on the number of installed plugins.
+
+__Can I still see the legacy API reference page?__
+
+Yes. The legacy API reference remains available for compatibility and migration purposes while transitioning to the new API documentation.
+
+__Why do some request or response schemas appear incomplete?__
+
+The API Reference plugin generates request and response examples using data available in your Matomo instance. As a result, some response examples may appear incomplete if there is limited or no matching data available for a specific API request.
+
+Not all API methods include response examples. Response examples are primarily generated for API methods that retrieve data from Matomo.
+
+__Does the API Reference plugin replace existing Matomo APIs?__
+
+No. The plugin modernises the API documentation experience while remaining compatible with existing Matomo APIs and integrations.
+
+Existing API endpoints and integrations continue to function normally.

plugin.json

@@ -1,7 +1,7 @@
 {
     "name": "ApiReference",
-    "description": "Generate and view API documentation for Matomo in the OpenAPI format.",
-    "version": "5.0.0",
+    "description": "Modern interactive API documentation for Matomo based on OpenAPI (Swagger). Explore endpoints, parameters, and responses directly in your browser. ",
+    "version": "5.0.2",
     "theme": false,
     "keywords": [
         "API",