Frontend API documentation, #PG-5031

[lachiebol]

Description

New page added at
index.php?module=OpenApiDocs&action=swagger&idSite=1&period=day&date=yesterday

Issue No

Steps to Replicate the Issue

Checklist

• [✔] Tested locally or on demo2/demo3?
• [✔] New test case added/updated?
• [✔] Are all newly added texts included via translation?
• [NA] Are text sanitized properly? (Eg use of v-text v/s v-html for vue)
• [NA] Version bumped?
• [NA] Documentation updated?

[lachiebol]

@AltamashShaikh Have just copied this in manually, might need some guidance on where to put swagger-ui. I wasn't sure if we needed to use npm or not

[AltamashShaikh]

@lachiebol We can use npm and ship the same with plugins, this will be easy to update next time. We can also add it under libs/swagger-ui/ and css via stylesheets/swagger-ui.

We should basically think, how will we upgrade the library next time if needed, won't npm be sufficient ?

[lachiebol]

@AltamashShaikh Using npm now, there's an npm script as well to move the files we need into a directory /lib/

[AltamashShaikh]

@lachiebol

The execute button and Request URL colours is too light, not readable

[AltamashShaikh]

This should point to my instance right ?

[lachiebol]

This should point to my instance right ?

@AltamashShaikh That's handled on the spec generation side, if you have generated any specs with this PR they'll have your local instance (#34)

[AltamashShaikh]

Can view the authorize button and works well locally 👍

[AltamashShaikh]

@lachiebol Codex review

Medium-risk issues

  - The new page is explicitly superuser-only in Controller.php:21 and Menu.php:19, but the backing API methods the page depends on still allow any user with view access in API.php:33 and
    API.php:55. If the intent is that Swagger docs are admin-only, this does not actually enforce it: a non-superuser can bypass the controller entirely and call OpenApiDocs.getPluginWhitelist /
    OpenApiDocs.getOpenApiSpec directly.
  - The plugin now registers plugins/OpenApiDocs/vue/dist/OpenApiDocs.css manually in OpenApiDocs.php:32, but Matomo already auto-adds plugins/$plugin/vue/dist/$plugin.css for Vue UMD plugins in /
    var/www/html/work/matomo/core/AssetManager/UIAssetFetcher/StylesheetUIAssetFetcher.php:92. That means the same CSS file is loaded twice. It is not catastrophic, but it adds avoidable asset
    weight and can complicate CSS debugging/order.

  Low-risk / polish

  - The README now contains machine-specific absolute links such as /home/lachlan/... in README.md:8. Those links will be broken for every other developer and on GitHub. They should be plain
    relative repo paths or inline code paths instead.

I think we can change the access to view/write user for menu, should keep it same as what we have for API.

[lachiebol]

@lachiebol Codex review

Medium-risk issues

  - The new page is explicitly superuser-only in Controller.php:21 and Menu.php:19, but the backing API methods the page depends on still allow any user with view access in API.php:33 and
    API.php:55. If the intent is that Swagger docs are admin-only, this does not actually enforce it: a non-superuser can bypass the controller entirely and call OpenApiDocs.getPluginWhitelist /
    OpenApiDocs.getOpenApiSpec directly.
  - The plugin now registers plugins/OpenApiDocs/vue/dist/OpenApiDocs.css manually in OpenApiDocs.php:32, but Matomo already auto-adds plugins/$plugin/vue/dist/$plugin.css for Vue UMD plugins in /
    var/www/html/work/matomo/core/AssetManager/UIAssetFetcher/StylesheetUIAssetFetcher.php:92. That means the same CSS file is loaded twice. It is not catastrophic, but it adds avoidable asset
    weight and can complicate CSS debugging/order.

  Low-risk / polish

  - The README now contains machine-specific absolute links such as /home/lachlan/... in README.md:8. Those links will be broken for every other developer and on GitHub. They should be plain
    relative repo paths or inline code paths instead.

I think we can change the access to view/write user for menu, should keep it same as what we have for API.

@AltamashShaikh Fixed these 👍

Just rebased and pulled in the backend changes, it should be using the new API endpoint now.

[AltamashShaikh]

@lachiebol This should check view access right ?

[AltamashShaikh]

@lachiebol This does make sense, can we include it in vue or via twig ?

OpenApiDocs.php:23-41: Swagger assets are registered globally through AssetManager.getStylesheetFiles / getJavaScriptFiles, so every Matomo page pays for this feature. The bundled files are
    large: swagger-ui-bundle.js is about 1.53 MB, swagger-ui.css about 179 KB. Even before gzip, that is a substantial global tax for a single admin page, plus broader CSS/JS collision surface. This
    should be page-scoped if Matomo’s asset pipeline allows it

[lachiebol]

@AltamashShaikh Fixed those, I also fixed the annotation generation issue.

You should be able to force the task to run with this:

core:run-scheduled-tasks "Piwik\Plugins\OpenApiDocs\Tasks.generateConfiguredPluginSpecs"

[AltamashShaikh]

@lachiebol We should also create an FAQ, explaining how you can build the missing spec or it will be auto generated if flag is set, so that user's don't reach out to support after activating the plugin.

[lachiebol]

@lachiebol We should also create an FAQ, explaining how you can build the missing spec or it will be auto generated if flag is set, so that user's don't reach out to support after activating the plugin.

Would this be a part of the checklist? Adding relevant documentation?

[AltamashShaikh]

@lachiebol LGTM 👍