Matomo Swagger Plugin

Description

Explore and try every Matomo API method straight from your admin panel. Swagger adds an interactive API explorer to Matomo, powered by Swagger UI and an OpenAPI 3.1 specification generated live from the plugins activated on your Matomo.

No static file to maintain, no manual sync after installing or removing a plugin: open the page and every Reporting API method of your installation is there, documented and ready to call.

It is built for developers integrating with Matomo, support engineers debugging a setup, and anyone who would rather click "Try it out" than write curl commands by hand.

New in 6.0

• Matomo 6 ready: rebuilt on the Matomo 6 Vue components, with dark mode support.
• No token needed to try the API: requests are sent with your current Matomo session. Paste an API token with Authorize only when you want to test a specific token.
• Up to date Swagger UI (5.x) with a search field to filter the API modules.
• Method descriptions taken from the Matomo source code, with summaries and deprecation flags.
• Report parameters documented: filter_limit, filter_sort_column, flat, format_metrics, showColumns and more on every report method.
• Download the OpenAPI JSON in one click, for Postman, Insomnia or an SDK generator.
• Embeddable as a Matomo widget with the Widgetize module.

What you get

• A Swagger API explorer page under Administration > Platform > Swagger, restricted to Super Users.
• An OpenAPI 3.1.0 document served by the Swagger.getOpenApi API method.
• Every method described as a POST request, so it keeps working with tokens restricted to POST requests.
• Parameter schemas typed from the PHP signatures (int, bool, float, array), with required flags and default values.
• Matomo specific schemas: period is a list, idSite accepts 1, 1,2,3 or all, date documents its keywords and ranges, segment and language carry usable descriptions.
• Request examples generated by the Matomo API documentation generator.
• Every response format Matomo can return (json, xml, csv, tsv, html, rss, original).

Requirements

• Matomo 6.0 or later.
• PHP 8.1 or later.
• A Super User account.

Installation

Install the plugin from the Matomo Marketplace, or copy it to plugins/Swagger and activate it under Administration > System > Plugins. The plugin creates no database table and leaves no data behind when deactivated.

Usage

1. Open Administration > Platform > Swagger.
2. Filter or expand an API module, then open a method.
3. Click Try it out, fill in the parameters and click Execute.

Requests use your Matomo session by default. To test with an API token instead, untick Send requests with my current Matomo session, click Authorize and paste a token created under Administration > Personal > Security.

Security

• The Swagger page, the widget and the Swagger.getOpenApi method require Super User access.
• The plugin never stores tokens: a token entered with Authorize only lives in the browser tab.
• The OpenAPI document describes the API methods only. It contains no credentials, configuration values or website data.

Support

• Documentation: https://openmost.com/matomo/extensions/swagger
• Issues and feature requests: https://github.com/openmost/Swagger/issues
• Commercial support and custom plugins: ronan@openmost.com

License

GPL v3 or later. Swagger UI is bundled under the Apache 2.0 license.