Updated marketplace information

Author: lachiebol

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 @@
+## 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.

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": [