feat(api-docs): extract API docs viewer into standalone module

Move the Swagger UI viewer from core (pages/admin/api-docs/) into modules/api-docs/ as a self-contained module. Create module manifest with routes, permission, sidebar.admin_nav_item slot, asset group, and authorization policy. Remove API docs ability from core OperationsAuthorizationPolicy and UiCapabilityMap. Remove hardcoded sidebar nav item — now contributed via module slot. Add admin-automation group meta to sidebar template for module nav items. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 14:02:42 +01:00
parent 5c86c56dec
commit 02a7d2fe90
15 changed files with 142 additions and 25 deletions
--- a/config/assets.php
+++ b/config/assets.php
@@ -58,9 +58,6 @@ return [
            'page-layout' => [
                'css/layout/app-page-layout.css',
            ],
-            'api-docs' => [
-                'css/vendor-overrides/swagger-ui.css',
-            ],
            'docs' => [
                'css/pages/app-docs.css',
            ],
--- a/config/modules.php
+++ b/config/modules.php
@@ -12,5 +12,5 @@
 * Each entry must match a directory name under modules/ containing a module.php manifest.
 */
 return [
-    'enabled_modules' => ['audit', 'addressbook', 'bookmarks', 'notifications'],
+    'enabled_modules' => ['audit', 'addressbook', 'bookmarks', 'notifications', 'api-docs'],
 ];
--- a/lib/Service/Access/OperationsAuthorizationPolicy.php
+++ b/lib/Service/Access/OperationsAuthorizationPolicy.php
@@ -12,7 +12,6 @@ final class OperationsAuthorizationPolicy implements AuthorizationPolicyInterfac
    public const ABILITY_ADMIN_MAIL_LOG_VIEW = 'ops.admin.mail_log.view';
    public const ABILITY_ADMIN_STATS_VIEW = 'ops.admin.stats.view';
    public const ABILITY_ADMIN_SYSTEM_INFO_VIEW = 'ops.admin.system_info.view';
-    public const ABILITY_ADMIN_API_DOCS_VIEW = 'ops.admin.api_docs.view';
    public const ABILITY_ADMIN_IMPORTS_TYPE_USERS = 'ops.admin.imports.type.users';
    public const ABILITY_ADMIN_IMPORTS_TYPE_DEPARTMENTS = 'ops.admin.imports.type.departments';
    public const ABILITY_ADMIN_USERS_ASSIGNMENTS_MANAGE = 'ops.admin.users.assignments.manage';
@@ -51,7 +50,6 @@ final class OperationsAuthorizationPolicy implements AuthorizationPolicyInterfac
            self::ABILITY_ADMIN_MAIL_LOG_VIEW,
            self::ABILITY_ADMIN_STATS_VIEW,
            self::ABILITY_ADMIN_SYSTEM_INFO_VIEW,
-            self::ABILITY_ADMIN_API_DOCS_VIEW,
            self::ABILITY_ADMIN_IMPORTS_TYPE_USERS,
            self::ABILITY_ADMIN_IMPORTS_TYPE_DEPARTMENTS,
            self::ABILITY_ADMIN_USERS_ASSIGNMENTS_MANAGE,
@@ -94,7 +92,6 @@ final class OperationsAuthorizationPolicy implements AuthorizationPolicyInterfac
            self::ABILITY_ADMIN_MAIL_LOG_VIEW => $this->allowIfHas($actorUserId, PermissionService::MAIL_LOG_VIEW),
            self::ABILITY_ADMIN_STATS_VIEW => $this->allowIfHas($actorUserId, PermissionService::STATS_VIEW),
            self::ABILITY_ADMIN_SYSTEM_INFO_VIEW => $this->allowIfHas($actorUserId, PermissionService::SYSTEM_INFO_VIEW),
-            self::ABILITY_ADMIN_API_DOCS_VIEW => $this->allowIfHas($actorUserId, PermissionService::API_DOCS_VIEW),
            self::ABILITY_ADMIN_IMPORTS_TYPE_USERS => $this->allowIfHas($actorUserId, PermissionService::USERS_IMPORT),
            self::ABILITY_ADMIN_IMPORTS_TYPE_DEPARTMENTS => $this->allowIfHas($actorUserId, PermissionService::DEPARTMENTS_IMPORT),
            self::ABILITY_ADMIN_USERS_ASSIGNMENTS_MANAGE => $this->allowIfHas($actorUserId, PermissionService::USERS_UPDATE_ASSIGNMENTS),
--- a/lib/Service/Access/UiCapabilityMap.php
+++ b/lib/Service/Access/UiCapabilityMap.php
@@ -21,7 +21,6 @@ final class UiCapabilityMap
        'can_view_settings' => SettingsAuthorizationPolicy::ABILITY_ADMIN_SETTINGS_VIEW,
        'can_view_imports' => OperationsAuthorizationPolicy::ABILITY_ADMIN_IMPORTS_VIEW,
        'can_view_jobs' => OperationsAuthorizationPolicy::ABILITY_ADMIN_JOBS_VIEW,
-        'can_view_api_docs' => OperationsAuthorizationPolicy::ABILITY_ADMIN_API_DOCS_VIEW,
        'can_view_docs' => OperationsAuthorizationPolicy::ABILITY_ADMIN_DOCS_VIEW,
        'can_view_mail_log' => OperationsAuthorizationPolicy::ABILITY_ADMIN_MAIL_LOG_VIEW,
        'can_view_stats' => OperationsAuthorizationPolicy::ABILITY_ADMIN_STATS_VIEW,
--- a/modules/api-docs/i18n/default_de.json
+++ b/modules/api-docs/i18n/default_de.json
@@ -0,0 +1,5 @@
+{
+  "API docs": "API-Dokumentation",
+  "API documentation": "API-Dokumentation",
+  "Can view API documentation": "Kann API-Dokumentation anzeigen"
+}
--- a/modules/api-docs/i18n/default_en.json
+++ b/modules/api-docs/i18n/default_en.json
@@ -0,0 +1,5 @@
+{
+  "API docs": "API docs",
+  "API documentation": "API documentation",
+  "Can view API documentation": "Can view API documentation"
+}
--- a/modules/api-docs/lib/Module/ApiDocs/ApiDocsAuthorizationPolicy.php
+++ b/modules/api-docs/lib/Module/ApiDocs/ApiDocsAuthorizationPolicy.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace MintyPHP\Module\ApiDocs;
+
+use MintyPHP\Service\Access\AuthorizationDecision;
+use MintyPHP\Service\Access\AuthorizationPolicyInterface;
+use MintyPHP\Service\Access\PermissionService;
+
+final class ApiDocsAuthorizationPolicy implements AuthorizationPolicyInterface
+{
+    public const ABILITY_VIEW = 'api_docs.view';
+    public const PERMISSION_KEY = 'api_docs.view';
+
+    public function __construct(
+        private readonly PermissionService $permissionService
+    ) {
+    }
+
+    public function supports(string $ability): bool
+    {
+        return $ability === self::ABILITY_VIEW;
+    }
+
+    public function authorize(string $ability, array $context = []): AuthorizationDecision
+    {
+        $actorUserId = (int) ($context['actor_user_id'] ?? 0);
+        if ($actorUserId <= 0) {
+            return AuthorizationDecision::deny(403, 'forbidden');
+        }
+
+        if (!$this->permissionService->userHas($actorUserId, self::PERMISSION_KEY)) {
+            return AuthorizationDecision::deny(403, 'forbidden');
+        }
+
+        return AuthorizationDecision::allow();
+    }
+}
--- a/modules/api-docs/lib/Module/ApiDocs/ApiDocsContainerRegistrar.php
+++ b/modules/api-docs/lib/Module/ApiDocs/ApiDocsContainerRegistrar.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace MintyPHP\Module\ApiDocs;
+
+use MintyPHP\App\AppContainer;
+use MintyPHP\App\Container\ContainerRegistrar;
+use MintyPHP\Service\Access\PermissionService;
+
+final class ApiDocsContainerRegistrar implements ContainerRegistrar
+{
+    public function register(AppContainer $container): void
+    {
+        $container->set(ApiDocsAuthorizationPolicy::class, static fn (AppContainer $c): ApiDocsAuthorizationPolicy => new ApiDocsAuthorizationPolicy(
+            $c->get(PermissionService::class)
+        ));
+    }
+}
--- a/modules/api-docs/module.php
+++ b/modules/api-docs/module.php
@@ -0,0 +1,66 @@
+<?php
+
+/**
+ * API Docs module manifest.
+ *
+ * Provides a Swagger UI viewer for the project's OpenAPI specification.
+ */
+return [
+    'id' => 'api-docs',
+    'version' => '1.0.0',
+    'enabled_by_default' => false,
+    'load_order' => 20,
+    'requires' => [],
+
+    'routes' => [
+        ['path' => 'admin/api-docs', 'target' => 'api-docs'],
+        ['path' => 'admin/api-docs/spec', 'target' => 'api-docs/spec'],
+    ],
+    'public_paths' => [],
+    'container_registrars' => [
+        \MintyPHP\Module\ApiDocs\ApiDocsContainerRegistrar::class,
+    ],
+
+    'ui_slots' => [
+        'sidebar.admin_nav_item' => [
+            [
+                'key' => 'api-docs',
+                'group' => 'admin-automation',
+                'label' => 'API docs',
+                'path' => 'admin/api-docs',
+                'permission' => 'api_docs.view',
+                'order' => 300,
+            ],
+        ],
+    ],
+
+    'authorization_policies' => [
+        \MintyPHP\Module\ApiDocs\ApiDocsAuthorizationPolicy::class,
+    ],
+
+    'search_resources' => [],
+
+    'asset_groups' => [
+        'api-docs' => [
+            'modules/api-docs/css/vendor-overrides/swagger-ui.css',
+        ],
+    ],
+
+    'scheduler_jobs' => [],
+    'layout_context_providers' => [],
+    'session_providers' => [],
+
+    'permissions' => [
+        [
+            'key' => 'api_docs.view',
+            'description' => 'Can view API documentation',
+            'active' => true,
+            'is_system' => true,
+        ],
+    ],
+
+    'event_listeners' => [],
+    'deactivation_handler' => null,
+    'migrations_path' => null,
+    'i18n_path' => 'i18n',
+];
--- a/modules/api-docs/pages/api-docs/index().php
+++ b/modules/api-docs/pages/api-docs/index().php
@@ -1,10 +1,11 @@
 <?php

 use MintyPHP\Buffer;
+use MintyPHP\Module\ApiDocs\ApiDocsAuthorizationPolicy;
 use MintyPHP\Support\Guard;

 Guard::requireLogin();
-Guard::requireAbility(\MintyPHP\Service\Access\OperationsAuthorizationPolicy::ABILITY_ADMIN_API_DOCS_VIEW);
+Guard::requireAbilityOrForbidden(ApiDocsAuthorizationPolicy::ABILITY_VIEW);

 Buffer::set('title', t('API docs'));
 Buffer::set('style_groups', json_encode(['api-docs']));
--- a/modules/api-docs/pages/api-docs/index(default).phtml
+++ b/modules/api-docs/pages/api-docs/index(default).phtml
@@ -12,4 +12,4 @@ require templatePath('partials/app-breadcrumb.phtml');
 </div>

 <script src="<?php e(assetVersion('vendor/swagger-ui/swagger-ui-bundle.js')); ?>"></script>
-<script type="module" src="<?php e(assetVersion('js/pages/admin-api-docs-index.js')); ?>"></script>
+<script type="module" src="<?php e(assetVersion('modules/api-docs/js/pages/admin-api-docs-index.js')); ?>"></script>
--- a/modules/api-docs/pages/api-docs/spec().php
+++ b/modules/api-docs/pages/api-docs/spec().php
@@ -1,14 +1,14 @@
 <?php

+use MintyPHP\Module\ApiDocs\ApiDocsAuthorizationPolicy;
 use MintyPHP\Support\Guard;

 define('MINTY_ALLOW_OUTPUT', true);

 Guard::requireLogin();
-Guard::requireAbility(\MintyPHP\Service\Access\OperationsAuthorizationPolicy::ABILITY_ADMIN_API_DOCS_VIEW);
+Guard::requireAbilityOrForbidden(ApiDocsAuthorizationPolicy::ABILITY_VIEW);

-$projectRoot = dirname(__DIR__, 3);
-$specPath = $projectRoot . '/docs/openapi.yaml';
+$specPath = defined('APP_ROOT') ? APP_ROOT . '/docs/openapi.yaml' : dirname(__DIR__, 4) . '/docs/openapi.yaml';

 if (!is_file($specPath)) {
    http_response_code(404);
--- a/modules/api-docs/web/css/vendor-overrides/swagger-ui.css
+++ b/modules/api-docs/web/css/vendor-overrides/swagger-ui.css
@@ -1,4 +1,4 @@
-@import url("../../vendor/swagger-ui/swagger-ui.css") layer(vendor);
+@import url("../../../../vendor/swagger-ui/swagger-ui.css") layer(vendor);

@layer vendor-overrides {
  .app-swagger-container {
--- a/modules/api-docs/web/js/pages/admin-api-docs-index.js
+++ b/modules/api-docs/web/js/pages/admin-api-docs-index.js
--- a/templates/partials/app-main-aside.phtml
+++ b/templates/partials/app-main-aside.phtml
@@ -14,7 +14,6 @@ $canViewPermissions = (bool) ($layoutAuth['can_view_permissions'] ?? false);
 $canViewSettings = (bool) ($layoutAuth['can_view_settings'] ?? false);
 $canViewImports = (bool) ($layoutAuth['can_view_imports'] ?? false);
 $canViewJobs = (bool) ($layoutAuth['can_view_jobs'] ?? false);
-$canViewApiDocs = (bool) ($layoutAuth['can_view_api_docs'] ?? false);
 $canViewDocs = (bool) ($layoutAuth['can_view_docs'] ?? false);
 $canViewMailLog = (bool) ($layoutAuth['can_view_mail_log'] ?? false);
 $canViewStats = (bool) ($layoutAuth['can_view_stats'] ?? false);
@@ -23,7 +22,7 @@ $docsDefaultSlug = DocsCatalogService::defaultSlug();
 $docsDefaultPath = 'admin/docs/' . $docsDefaultSlug;
 $hasOrganization = $canViewTenants || $canViewDepartments || $canViewUsers;
 $hasUsersSection = $canViewRoles || $canViewPermissions;
-$hasAutomationSection = $canViewImports || $canViewJobs || $canViewApiDocs;
+$hasAutomationSection = $canViewImports || $canViewJobs;
 $hasMonitoringSection = $canViewStats;
 $hasLogsSection = $canViewMailLog;
 $hasSystemSection = $canViewSettings || $canViewSystemInfo || $canViewDocs;
@@ -102,13 +101,6 @@ $adminNavGroups = [
                'visible' => $canViewJobs,
                'withTenant' => false,
            ],
-            [
-                'label' => t('API docs'),
-                'path' => 'admin/api-docs',
-                'active' => navActive('admin/api-docs', true),
-                'visible' => $canViewApiDocs,
-                'withTenant' => false,
-            ],
        ],
    ],
    [
@@ -133,7 +125,7 @@ $adminNavGroups = [
        'visible' => $hasLogsSection,
        'items' => [
            [
-                'label' => t('Mail logs'),
+                'label' => t('nav.logs.mail'),
                'path' => 'admin/mail-log',
                'active' => navActive('admin/mail-log', true),
                'visible' => $canViewMailLog,
@@ -199,6 +191,7 @@ if ($moduleNavItemSlots) {
    }
    // Known group metadata — modules declare their group key, we map to label + icon.
    $moduleGroupMeta = [
+        'admin-automation' => ['label' => t('Automation & integrations'), 'icon' => 'bi-gear-wide-connected'],
        'admin-logs' => ['label' => t('Audit & logs'), 'icon' => 'bi-journal-text'],
    ];
    foreach ($moduleGroupsByKey as $groupKey => $items) {
@@ -209,7 +202,7 @@ if ($moduleNavItemSlots) {
        // Also add mail log to the logs group if it exists as a core item
        if ($groupKey === 'admin-logs' && $canViewMailLog) {
            array_unshift($items, [
-                'label' => t('Mail logs'),
+                'label' => t('nav.logs.mail'),
                'path' => 'admin/mail-log',
                'active' => navActive('admin/mail-log', true),
                'visible' => $canViewMailLog,