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/modules/api-docs/web/css/vendor-overrides/swagger-ui.css
+++ b/modules/api-docs/web/css/vendor-overrides/swagger-ui.css
@@ -0,0 +1,176 @@
+@import url("../../../../vendor/swagger-ui/swagger-ui.css") layer(vendor);
+
+@layer vendor-overrides {
+  .app-swagger-container {
+    background: var(--app-background-color);
+    color: var(--app-color);
+  }
+
+  .swagger-ui {
+    color: var(--app-color);
+    font-family: var(--app-font-family);
+  }
+
+  .swagger-ui .info .title,
+  .swagger-ui .info h1,
+  .swagger-ui .info h2,
+  .swagger-ui .info h3,
+  .swagger-ui h1,
+  .swagger-ui h2,
+  .swagger-ui h3,
+  .swagger-ui h4 {
+    color: var(--app-color);
+  }
+
+  .swagger-ui .info a,
+  .swagger-ui a.nostyle,
+  .swagger-ui a.nostyle:visited {
+    color: var(--app-primary);
+  }
+
+  .swagger-ui .scheme-container {
+    background: var(--app-card-background-color);
+    box-shadow: none;
+    border: var(--app-border-width) solid var(--app-form-element-border-color);
+    border-radius: var(--app-border-radius);
+  }
+
+  .swagger-ui .opblock {
+    border-color: var(--app-form-element-border-color);
+    border-radius: var(--app-border-radius);
+    background: var(--app-card-background-color);
+  }
+
+  .swagger-ui .opblock .opblock-summary {
+    border-color: var(--app-form-element-border-color);
+  }
+
+  .swagger-ui .opblock-tag {
+    border-color: var(--app-form-element-border-color);
+    color: var(--app-color);
+  }
+
+  .swagger-ui .responses-inner h4,
+  .swagger-ui .responses-inner h5,
+  .swagger-ui .response-col_status,
+  .swagger-ui .response-col_description__inner p,
+  .swagger-ui .tab li,
+  .swagger-ui .model-title {
+    color: var(--app-color);
+  }
+
+  .swagger-ui .parameter__name,
+  .swagger-ui .parameter__type,
+  .swagger-ui .parameter__deprecated,
+  .swagger-ui .parameter__in {
+    color: var(--app-color);
+  }
+
+  .swagger-ui input[type="text"],
+  .swagger-ui input[type="password"],
+  .swagger-ui input[type="search"],
+  .swagger-ui input[type="email"],
+  .swagger-ui textarea,
+  .swagger-ui select {
+    background: var(--app-form-element-background-color);
+    color: var(--app-form-element-color);
+    border: var(--app-border-width) solid var(--app-form-element-border-color);
+    border-radius: var(--app-border-radius);
+    box-shadow: none;
+  }
+
+  .swagger-ui input[type="text"]:focus,
+  .swagger-ui input[type="password"]:focus,
+  .swagger-ui input[type="search"]:focus,
+  .swagger-ui input[type="email"]:focus,
+  .swagger-ui textarea:focus,
+  .swagger-ui select:focus {
+    border-color: var(--app-primary);
+    box-shadow: 0 0 0 var(--app-outline-width) var(--app-primary-focus);
+    outline: none;
+  }
+
+  .swagger-ui .btn {
+    border-radius: var(--app-border-radius);
+  }
+
+  .swagger-ui .btn.authorize {
+    color: var(--app-primary);
+    border-color: var(--app-primary);
+  }
+
+  .swagger-ui .btn.authorize svg {
+    fill: currentColor;
+  }
+
+  .swagger-ui .model-box,
+  .swagger-ui .highlight-code,
+  .swagger-ui .microlight,
+  .swagger-ui .responses-table .response-col_description__inner {
+    background: var(--app-card-background-color);
+    color: var(--app-color);
+  }
+
+  /* Reset all Pico CSS button styles that bleed into Swagger UI */
+  .swagger-ui button {
+    cursor: pointer;
+    background: transparent;
+    border: 0;
+    padding: 0;
+    margin: 0;
+    color: inherit;
+    font-size: inherit;
+    font-weight: inherit;
+    font-family: inherit;
+    line-height: inherit;
+    border-radius: 0;
+    box-shadow: none;
+    text-transform: none;
+    /* Reset CSS custom properties set by app base styles on all buttons */
+    --app-background-color: initial;
+    --app-border-color: initial;
+    --app-color: initial;
+    --app-box-shadow: initial;
+  }
+
+  /* Restore sizing/appearance for Swagger UI action buttons (.btn) */
+  .swagger-ui .btn {
+    padding: 6px 23px;
+    font-size: 14px;
+    font-weight: 700;
+    border: 2px solid transparent;
+    border-radius: var(--app-border-radius);
+    background: transparent;
+  }
+
+  .swagger-ui .opblock .opblock-summary-description {
+    color: var(--app-color);
+  }
+
+  .swagger-ui .opblock .opblock-section-header {
+    background: var(--app-accordion-border-color);
+  }
+
+  .swagger-ui section {
+    margin: 0;
+  }
+
+  .swagger-ui .servers > label {
+    margin: 0;
+  }
+
+  pre.version {
+    all: inherit;
+    padding: 0;
+    margin: 0;
+    font-size: inherit;
+  }
+
+  .swagger-ui .info .title small {
+    top: 0;
+  }
+
+  select#servers {
+    margin: 0;
+  }
+}
--- a/modules/api-docs/web/js/pages/admin-api-docs-index.js
+++ b/modules/api-docs/web/js/pages/admin-api-docs-index.js
@@ -0,0 +1,16 @@
+const container = document.getElementById('swagger-ui');
+
+if (container && window.SwaggerUIBundle) {
+  window.SwaggerUIBundle({
+    url: container.dataset.specUrl || '',
+    dom_id: '#swagger-ui',
+    deepLinking: false,
+    displayRequestDuration: true,
+    filter: true,
+    docExpansion: 'list',
+    supportedSubmitMethods: [],
+    tryItOutEnabled: false,
+    presets: [window.SwaggerUIBundle.presets.apis],
+    layout: 'BaseLayout',
+  });
+}