From 1693b14dc633224d9d549d46133421e313046c0d Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Mon, 25 May 2026 11:54:02 +1200 Subject: [PATCH 1/4] No longer providing examples for methods that don't return a valid API response --- Annotations/AnnotationGenerator.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Annotations/AnnotationGenerator.php b/Annotations/AnnotationGenerator.php index 8216e24..73fc14b 100644 --- a/Annotations/AnnotationGenerator.php +++ b/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 []; From e67243e2923b397ab1e92042d40be0cbf8f158a0 Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Mon, 25 May 2026 11:55:37 +1200 Subject: [PATCH 2/4] update changelog --- CHANGELOG.md | 3 +++ plugin.json | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f108f5b..fef2201 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ ## Changelog +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 diff --git a/plugin.json b/plugin.json index 3925ba6..5d516b7 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "name": "ApiReference", "description": "Generate and view API documentation for Matomo in the OpenAPI format.", - "version": "5.0.0", + "version": "5.0.1", "theme": false, "keywords": [ "API", From aa1b8e93a1a1b82a48e9911087f9732cd889ec40 Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Mon, 25 May 2026 11:56:49 +1200 Subject: [PATCH 3/4] fix typo --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fef2201..647e13a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ ## Changelog 5.0.1 - 25/05/2026 -- Added fix for endpoints that don't return valid API responses: +- Added fix for endpoints that don't return valid API responses 5.0.0 - Initial release of ApiReference plugin From 15e29d7256272219dc160bf20d8be68712b059f6 Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Mon, 25 May 2026 15:42:02 +1200 Subject: [PATCH 4/4] Updated marketplace information --- README.md | 3 ++- docs/faq.md | 39 +++++++++++++++++++++++++++++++++++++++ plugin.json | 2 +- 3 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 docs/faq.md diff --git a/README.md b/README.md index d982a4b..61cabdf 100644 --- a/README.md +++ b/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 diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..b9e7e7a --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,39 @@ +## 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: + + +The initial generation process may take some time to complete, depending on the number of installed plugins. + + +```bash +core:run-scheduled-tasks "Piwik\Plugins\ApiReference\Tasks.generateConfiguredPluginSpecs" +``` + +## 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. diff --git a/plugin.json b/plugin.json index 5d516b7..7096eea 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "ApiReference", - "description": "Generate and view API documentation for Matomo in the OpenAPI format.", + "description": "Modern interactive API documentation for Matomo based on OpenAPI (Swagger). Explore endpoints, parameters, and responses directly in your browser. ", "version": "5.0.1", "theme": false, "keywords": [