go-duck-cli 1.3.3 → 1.3.5

package/README.md

@@ -59,8 +59,9 @@ GO-DUCK has officially reached the **410% Achievement Status**, evolving from a
 | **Silo Discovery & Privacy Proxy** | 🚀 **ELITE (+10%)** | Silo discovery API with physical DB name masking. |
 | **Universal Storage Mesh** | 🚀 **ELITE (+25%)** | Dynamic Hot-Swapping Registry and Distributed Cross-Scan API retrieval. |
 | **WSO2 API Gateway Integration** | 🚀 **ELITE (+15%)** | Automated OpenAPI registration & proxy mapping. |
+| **API Gateway Standards & Swagger UI** | 🚀 **ELITE (+10%)** | Keycloak SSO, Glassmorphism UI, JHipster `/v3/api-docs` compliance. |
 | **Full-Spectrum GDL Evolution** | 🚀 **ELITE (+15%)** | Native DROP/ALTER migrations with dead-code purging. |
-| **TOTAL ACHIEVEMENT STATUS** | 🏆 **410%** | **ELITE STATUS CONFIRMED.** 👑 |
+| **TOTAL ACHIEVEMENT STATUS** | 🏆 **420%** | **ELITE STATUS CONFIRMED.** 👑 |
 
 ### ✨ Primary Features (The 410% Core)
 
@@ -75,6 +76,8 @@ GO-DUCK has officially reached the **410% Achievement Status**, evolving from a
 *   **Distributed Saga Consistency**: Integrated **Transactional Outbox** pattern and background workers in every silo to guarantee eventual consistency across the federation.
 *   **Zero-Trust Identity Registry**: Decoupled mapping layer ensuring physical database names and internal IDs never leak to the client.
 *   **Universal Storage Mesh**: Dynamic Multi-Provider Registry allowing hot-swapping at runtime via `?provider=` queries, alongside Distributed Cross-Scan endpoints to auto-locate files across AWS, GCS, SFTP, and GitHub lakes.
+*   **Enterprise API Gateway Compatibility**: Natively exposes the Swagger/OpenAPI JSON specification at `/v3/api-docs` to ensure drop-in compatibility with **JHipster**, **WSO2 API Manager**, and Spring Boot ecosystems.
+*   **Next-Gen Swagger UI**: A fully glassmorphism-styled Swagger UI with seamless Keycloak SSO integration. Features automatic JWT token refresh, dynamic `X-Tenant-ID` header injection, and CLI metadata branding. Now features a **Live Interactive MQTT Dictionary**, allowing users to instantly subscribe or publish payloads directly from the docs via WebSockets!
 *   **Spring-style Elasticsearch Search**: Real-time sync for entities marked with `@Searchable`, supporting native `query_string` syntax (wildcards like `*`, booleans, ranges, and fuzzy matching).
 *   **SaaS Quota Engine**: Redis-backed API bandwidth tracking with dynamic, hierarchical limits (User vs. Role mapping).
 *   **Resilience Layer**: Sony/Gobreaker Integration + Zero-Trust Distributed Redis Rate Limiter.

package/generators/config.js

@@ -2,6 +2,11 @@ import fs from 'fs-extra';
 import path from 'path';
 import chalk from 'chalk';
 
+const toKebabCase = (str) => {
+	if (!str) return '';
+	return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+};
+
 export const generateConfigLoader = async (outputDir, configObj) => {
 	const configDir = path.join(outputDir, 'config');
 	await fs.ensureDir(configDir);
@@ -243,7 +248,7 @@ func LoadConfig() (*Config, error) {
 	// Default values
 	v.SetDefault("go-duck.server.rest.port", 8080)
 	v.SetDefault("go-duck.server.rest.protocol", "json")
-	v.SetDefault("go-duck.server.rest.api-path-prefix", "/${configObj.name || 'api'}/api")
+	v.SetDefault("go-duck.server.rest.api-path-prefix", "/${toKebabCase(configObj.name) || 'api'}/api")
 	v.SetDefault("go-duck.security.rate-limit.rps", 100.0)
 	v.SetDefault("go-duck.security.rate-limit.burst", 200)
 	v.SetDefault("go-duck.logging.datadog.enabled", false)

package/generators/devops.js

@@ -13,10 +13,15 @@ export const generateDeploymentArtifacts = async (config, projectRootDir) => {
     await fs.ensureDir(keycloakDir);
     await fs.ensureDir(githubDir);
 
+    const toKebabCase = (str) => {
+        if (!str) return '';
+        return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+    };
     const appName = config.name || 'go-duck';
+    const k8sAppName = toKebabCase(appName);
     const parts = appName.split(/[-_]/);
     const shortName = (parts.length > 1 ? parts.map(w => w[0]).join('') : appName).substring(0, 10).toLowerCase() || 'goduck';
-    const appPort = config.server?.port || 8080;
+    const appPort = config.server?.rest?.port || 8080;
     const keycloakHost = config.security?.['keycloak-host'] || 'http://localhost:8180';
     const keycloakPort = keycloakHost.includes(':') ? keycloakHost.split(':').pop() : '8080';
 
@@ -75,9 +80,11 @@ FROM gcr.io/distroless/static-debian12
 WORKDIR /app
 
 COPY --from=builder /app/server .
+
 COPY --from=builder /app/application.yml .
 COPY --from=builder /app/application-dev.yml .
 COPY --from=builder /app/application-prod.yml .
+COPY --from=builder /app/docs/ /app/docs/
 
 EXPOSE ${appPort}
 ENV GO_PROFILE=prod
@@ -468,21 +475,21 @@ echo "========================================="
     const k8sAppYaml = `apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: ${appName}
+  name: ${k8sAppName}
   labels:
-    app: ${appName}
+    app: ${k8sAppName}
 spec:
   replicas: 1
   selector:
     matchLabels:
-      app: ${appName}
+      app: ${k8sAppName}
   template:
     metadata:
       labels:
-        app: ${appName}
+        app: ${k8sAppName}
     spec:
       containers:
-        - name: ${appName}
+        - name: ${k8sAppName}
           image: ${appName}:latest
           env:
             - name: GO_PROFILE
@@ -490,7 +497,7 @@ spec:
             - name: GO_DUCK_SERVER_REST_PORT
               value: "${appPort}"
             - name: GO_DUCK_DATASOURCE_HOST
-              value: postgres.${shortName}-postgres-k8s.svc.cluster.local
+              value: postgres.${k8sAppName}-postgres-k8s.svc.cluster.local
             - name: GO_DUCK_DATASOURCE_USERNAME
               value: "${config.datasource?.username || 'postgres'}"
             - name: GO_DUCK_DATASOURCE_PASSWORD
@@ -502,31 +509,31 @@ spec:
             - name: GO_DUCK_DATASOURCE_MONGODB_ENABLED
               value: "${config.datasource?.mongodb?.enabled ? 'true' : 'false'}"
             - name: GO_DUCK_DATASOURCE_MONGODB_URI
-              value: mongodb://mongodb.${shortName}-mongodb-k8s.svc.cluster.local:27017
+              value: mongodb://mongodb.${k8sAppName}-mongodb-k8s.svc.cluster.local:27017
             - name: GO_DUCK_DATASOURCE_MONGODB_DATABASE
               value: "${config.datasource?.mongodb?.database || 'goduck_document_store'}"
             - name: GO_DUCK_CACHE_REDIS_HOST
-              value: redis.${shortName}-redis-k8s.svc.cluster.local:6379
+              value: redis.${k8sAppName}-redis-k8s.svc.cluster.local:6379
             - name: GO_DUCK_CACHE_REDIS_PASSWORD
               value: "${config.cache?.redis?.password || ''}"
             - name: GO_DUCK_MESSAGING_MQTT_BROKER
-              value: tcp://mosquitto.${shortName}-mosquitto-k8s.svc.cluster.local:1883
+              value: tcp://mosquitto.${k8sAppName}-mosquitto-k8s.svc.cluster.local:1883
             - name: GO_DUCK_MESSAGING_MQTT_USERNAME
               value: "${config.messaging?.mqtt?.username || 'dev_user'}"
             - name: GO_DUCK_MESSAGING_MQTT_PASSWORD
               value: "${config.messaging?.mqtt?.password || 'dev_password'}"
             - name: GO_DUCK_MESSAGING_NATS_URL
-              value: nats://nats.${shortName}-nats-k8s.svc.cluster.local:4222
+              value: nats://nats.${k8sAppName}-nats-k8s.svc.cluster.local:4222
             - name: GO_DUCK_TELEMETRY_OTEL_ENDPOINT
-              value: otel-collector.${shortName}-otel-collector-k8s.svc.cluster.local:4317
+              value: otel-collector.${k8sAppName}-otel-collector-k8s.svc.cluster.local:4317
             - name: GO_DUCK_ELASTICSEARCH_ADDRESSES
-              value: http://elasticsearch.${shortName}-elasticsearch-k8s.svc.cluster.local:9200
+              value: http://elasticsearch.${k8sAppName}-elasticsearch-k8s.svc.cluster.local:9200
             - name: GO_DUCK_ELASTICSEARCH_USERNAME
               value: "${config.elasticsearch?.username || 'elastic'}"
             - name: GO_DUCK_ELASTICSEARCH_PASSWORD
               value: "${config.elasticsearch?.password || 'changeme'}"
             - name: GO_DUCK_SECURITY_KEYCLOAK_HOST
-              value: http://keycloak.${shortName}-keycloak-k8s.svc.cluster.local:8080
+              value: http://keycloak.${k8sAppName}-keycloak-k8s.svc.cluster.local:8080
             - name: GO_DUCK_SECURITY_KEYCLOAK_REALM
               value: "${config.security?.['keycloak-realm'] || 'go-duck-realm'}"
             - name: GO_DUCK_SECURITY_KEYCLOAK_APP_CLIENT_ID
@@ -536,7 +543,7 @@ spec:
             - name: GO_DUCK_SECURITY_KEYCLOAK_SERVICE_SECRET
               value: "${config.security?.['keycloak-service-secret'] || 'service-secret-123'}"
             - name: GO_DUCK_STORAGE_MINIO_ENDPOINT
-              value: "http://minio.${shortName}-minio-k8s.svc.cluster.local:9000"
+              value: "http://minio.${k8sAppName}-minio-k8s.svc.cluster.local:9000"
             - name: GO_DUCK_STORAGE_MINIO_ACCESS_KEY
               value: "${config.storage?.minio?.['access-key'] || 'minioadmin'}"
             - name: GO_DUCK_STORAGE_MINIO_SECRET_KEY
@@ -550,7 +557,7 @@ spec:
 apiVersion: v1
 kind: Service
 metadata:
-  name: ${appName}
+  name: ${k8sAppName}
 spec:
   type: NodePort
   ports:
@@ -563,7 +570,7 @@ spec:
       targetPort: grpc
       nodePort: 30090
   selector:
-    app: ${appName}
+    app: ${k8sAppName}
 `;
 
     const k8sPostgresYaml = `apiVersion: v1
@@ -1001,7 +1008,7 @@ spec:
     await fs.writeFile(path.join(k8sDir, 'mosquitto.conf'), mosquittoConf);
     // Namespace calculation: unique namespace per service
     const applyNs = (yamlString, serviceName) => {
-        const nsName = `${shortName}-${serviceName}-k8s`;
+        const nsName = `${k8sAppName}-${serviceName}-k8s`;
         const nsBlock = `apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ${nsName}\n---\n`;
         return nsBlock + yamlString.replace(/^metadata:$/gm, `metadata:\n  namespace: ${nsName}`);
     };
@@ -1012,7 +1019,7 @@ spec:
     // We conditionally add minio if storage is enabled (or any blob provider), but for safety we'll just generate its namespace always.
     servicesList.push('minio');
 
-    const k8sNamespaceYaml = servicesList.map(svc => `apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ${shortName}-${svc}-k8s`).join('\n---\n');
+    const k8sNamespaceYaml = servicesList.map(svc => `apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ${k8sAppName}-${svc}-k8s`).join('\n---\n');
 
     await fs.writeFile(path.join(k8sDir, 'namespace.yaml'), k8sNamespaceYaml);
 

package/generators/docs.js

@@ -72,7 +72,7 @@ export const generateDocumentation = async (config, entities, outputDir, enums =
         entities: entities,
         enums: enums,
         openEntities: openEntities,
-        serverPort: config.server?.port || 8080,
+        serverPort: config.server?.rest?.port || 8080,
         grpcPort: grpcPort,
         mqttPort: mqttPort
     };

package/generators/mqtt-topics.js

@@ -0,0 +1,54 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+
+export const generateMQTTTopicsJSON = async (config, entities, outputDir) => {
+    const docsDir = path.join(outputDir, 'docs');
+    await fs.ensureDir(docsDir);
+
+    const jsonFilePath = path.join(docsDir, 'mqtt_topics.json5');
+    const needle = '// needle-mqtt-topics-add-below';
+
+    let content = '';
+    if (await fs.pathExists(jsonFilePath)) {
+        content = await fs.readFile(jsonFilePath, 'utf8');
+    } else {
+        content = `{
+  "topics": {
+    // Custom topics can be added here manually.
+    
+    ${needle}
+  }
+}`;
+    }
+
+    const topicPrefix = config.messaging?.mqtt?.['topic-prefix'] || 'go-duck/events';
+    let newEntries = '';
+
+    for (const entity of entities) {
+        const entityName = entity.name.toLowerCase();
+        const baseTopic = `${topicPrefix}/${entityName}`;
+
+        const createdTopic = `"${baseTopic}/created"`;
+        if (!content.includes(createdTopic)) {
+            newEntries += `    // Auto-generated topics for ${entity.name}\n`;
+            newEntries += `    ${createdTopic}: "Triggered when a new ${entity.name} is created.",\n`;
+            newEntries += `    "${baseTopic}/updated": "Triggered when an existing ${entity.name} is updated.",\n`;
+            newEntries += `    "${baseTopic}/deleted": "Triggered when a ${entity.name} is deleted.",\n\n`;
+        }
+    }
+
+    if (newEntries.length > 0) {
+        if (content.includes(needle)) {
+            content = content.replace(needle, newEntries + `    ${needle}`);
+        } else {
+            // Fallback if needle is missing somehow
+            content = content.replace(/}\s*}$/, `,\n${newEntries}\n  }\n}`);
+        }
+        
+        await fs.writeFile(jsonFilePath, content);
+        console.log(chalk.gray('  Updated MQTT Topics Dictionary: mqtt_topics.json5'));
+    } else {
+        console.log(chalk.gray('  MQTT Topics Dictionary up to date.'));
+    }
+};

package/generators/postman.js

@@ -18,7 +18,7 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
         item: [],
         variable: [
             { key: "host", value: "localhost", type: "string" },
-            { key: "port", value: String(config.server?.port || 8080), type: "string" },
+            { key: "port", value: String(config.server?.rest?.port || 8080), type: "string" },
             { key: "tenant", value: "tenant_1", type: "string" },
             { key: "token", value: "", type: "string" },
             { key: "keycloak_url", value: config.security?.['keycloak-host'] || "http://localhost:8180", type: "string" },
@@ -364,8 +364,9 @@ export const generatePostmanCollection = async (config, entities, outputDir, ope
             else if (f.type === 'Float' || f.type === 'BigDecimal') obj[f.name] = 99.99;
             else if (f.type === 'Boolean') obj[f.name] = true;
             else if (f.type === 'LocalDate') obj[f.name] = "2024-01-01";
-            else if (f.type === 'Instant') obj[f.name] = "2024-01-01T12:00:00Z";
+            else if (f.type === 'Instant' || f.type === 'DateTime' || f.type === 'Datetime') obj[f.name] = "2024-01-01T12:00:00Z";
             else if (f.type === 'JSON' || f.type === 'JSONB') obj[f.name] = {"attribute": "example_value"};
+            else if (f.isEnum) obj[f.name] = "ACTIVE"; // Safe fallback for enums
             else obj[f.name] = "test";
         }
         return JSON.stringify(obj, null, 2);

package/generators/router.js

@@ -19,10 +19,17 @@ export const generateRouterCode = async (outputDir, config, entities, openEntiti
     const templateSource = await fs.readFile(templatePath, 'utf8');
     const template = Handlebars.compile(templateSource);
 
+    const packageJsonPath = path.resolve(__dirname, '../package.json');
+    const packageJson = await fs.readJson(packageJsonPath);
+    const cliVersion = packageJson.version;
+    const generatedDate = new Date().toISOString();
+
     const content = template({
         app_name: config.name,
         entities,
-        openEntities
+        openEntities,
+        cli_version: cliVersion,
+        generated_date: generatedDate
     });
 
     await fs.writeFile(path.join(routerDir, 'router.go'), content);

package/generators/swagger.js

@@ -17,7 +17,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir, openEntit
             description: `Generated documentation for ${config.name} microservice`
         },
         servers: [
-            { url: `http://localhost:${config.server?.port || 8080}`, description: 'Local Development Server' }
+            { url: "/", description: "Current Host" }
         ],
         paths: {},
         components: {
@@ -51,7 +51,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir, openEntit
     };
 
     const commonHeaders = [
-        { name: 'X-Tenant-ID', in: 'header', required: true, schema: { type: 'string', default: 'default' }, description: 'Multi-tenancy context identifier' }
+        { name: 'X-Tenant-ID', in: 'header', required: false, schema: { type: 'string', default: 'default' }, description: 'Multi-tenancy context identifier' }
     ];
 
     const isOpen = (entityName, action) => {
@@ -84,7 +84,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir, openEntit
             properties: {
                 id: { type: 'integer' },
                 ...entity.fields.reduce((acc, field) => {
-                    acc[field.name] = { type: mapToSwaggerType(field.type) };
+                    acc[field.name] = getSwaggerFieldSchema(field.type);
                     return acc;
                 }, {}),
                 createdAt: { type: 'string', format: 'date-time' },
@@ -273,7 +273,7 @@ export const generateSwaggerDocs = async (config, entities, outputDir, openEntit
                 }
             },
             parameters: [
-                { name: 'X-Tenant-ID', in: 'header', required: true, schema: { type: 'string', default: 'master_internal' }, description: 'SuperAdmin internal master bypass token' }
+                { name: 'X-Tenant-ID', in: 'header', required: false, schema: { type: 'string', default: 'master_internal' }, description: 'SuperAdmin internal master bypass token' }
             ],
             responses: {
                 200: { description: 'Success' },
@@ -318,19 +318,19 @@ export const generateSwaggerDocs = async (config, entities, outputDir, openEntit
     console.log(chalk.gray('  Generated Swagger Documentation: swagger.json'));
 };
 
-const mapToSwaggerType = (type) => {
-    const types = {
-        'String': 'string',
-        'Integer': 'integer',
-        'Float': 'number',
-        'Boolean': 'boolean',
-        'Long': 'integer',
-        'BigDecimal': 'number',
-        'LocalDate': 'string',
-        'Instant': 'string',
-        'JSON': 'object',
-        'JSONB': 'object',
-        'Text': 'string'
+const getSwaggerFieldSchema = (type) => {
+    const schemas = {
+        'String': { type: 'string' },
+        'Integer': { type: 'integer', format: 'int32' },
+        'Float': { type: 'number', format: 'double' },
+        'Boolean': { type: 'boolean' },
+        'Long': { type: 'integer', format: 'int64' },
+        'BigDecimal': { type: 'number', format: 'double' },
+        'LocalDate': { type: 'string', format: 'date' },
+        'Instant': { type: 'string', format: 'date-time' },
+        'JSON': { type: 'object' },
+        'JSONB': { type: 'object' },
+        'Text': { type: 'string' }
     };
-    return types[type] || 'string';
+    return schemas[type] || { type: 'string' };
 };

package/index.js

@@ -31,6 +31,7 @@ import { generateWebSocketCode } from './generators/websocket.js';
 import { generateConfigLoader } from './generators/config.js';
 import { generateLoggerCode } from './generators/logger.js';
 import { generateMQTTCode } from './generators/mqtt.js';
+import { generateMQTTTopicsJSON } from './generators/mqtt-topics.js';
 import { generateCacheCode } from './generators/cache.js';
 import { generateResilienceCode } from './generators/resilience.js';
 import { generateTelemetryCode } from './generators/telemetry.js';
@@ -875,13 +876,21 @@ const generateYAMLConfigs = async (config, outputDir) => {
         delete cleanConfig.datasource['multitenancy-databases'];
     }
 
+    const toKebabCase = (str) => {
+        if (!str) return '';
+        return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+    };
+
+    const rawApiPrefix = cleanConfig.server?.rest?.['api-path-prefix'] || `/${cleanConfig.name || 'api'}/api`;
+    const kebabApiPrefix = rawApiPrefix.split('/').map(segment => toKebabCase(segment)).join('/');
+
     const extendedConfig = {
         ...cleanConfig,
         server: {
             rest: {
                 port: cleanConfig.server?.rest?.port || cleanConfig.server?.port || 8080,
                 protocol: cleanConfig.server?.rest?.protocol || 'json',
-                'api-path-prefix': cleanConfig.server?.rest?.['api-path-prefix'] || `/${cleanConfig.name || 'api'}/api`
+                'api-path-prefix': kebabApiPrefix
             },
             'read-timeout': cleanConfig.server?.['read-timeout'] || '30s',
             'write-timeout': cleanConfig.server?.['write-timeout'] || '30s',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "go-duck-cli",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "The Ultimate Evolutionary Go Microservice Scaffolder.",
   "main": "index.js",
   "type": "module",
@@ -10,6 +10,9 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "author": "heavenscode",
   "license": "ISC",
   "dependencies": {
@@ -21,5 +24,23 @@
     "inquirer": "^8.2.7",
     "js-yaml": "^4.1.1",
     "open": "^11.0.0"
+  },
+  "keywords": [
+    "go",
+    "golang",
+    "microservice",
+    "scaffold",
+    "cli",
+    "generator",
+    "go-duck"
+  ],
+  
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heavenscode/go-duck.git"
+  },
+  "homepage": "https://goduck.theheavenscode.com",
+  "bugs": {
+    "url": "https://github.com/heavenscode/go-duck/issues"
   }
 }

package/templates/docs/pages/index.hbs

@@ -16,7 +16,7 @@
                     <span class="animate-ping absolute inline-flex h-full w-full rounded-full bg-emerald-400 opacity-75"></span>
                     <span class="relative inline-flex rounded-full h-3 w-3 bg-emerald-500"></span>
                 </span>
-                <p class="text-[11px] font-black text-indigo-900 uppercase tracking-[0.25em]">The 395% Elite Milestone Surpassed</p>
+                <p class="text-[11px] font-black text-indigo-900 uppercase tracking-[0.25em]">The 420% Elite Milestone Surpassed</p>
             </div>
             
             <!-- Heroic Logo Anchor (Enhanced) -->
@@ -121,6 +121,16 @@
                     </div>
                 </div>
 
+                <div class="lg:col-span-12 bg-white p-10 rounded-[2.5rem] border border-amber-100 shadow-sm hover:shadow-2xl transition-all group relative overflow-hidden cursor-crosshair bg-gradient-to-br from-white to-amber-50/30">
+                    <p class="text-[9px] font-bold text-amber-600 uppercase tracking-widest mb-4">Elite Extension (+10%)</p>
+                    <h4 class="text-2xl font-black text-slate-900 mb-3 tracking-tight italic">API Gateway Standards & Swagger UI</h4>
+                    <p class="text-slate-600 leading-relaxed mb-8">Natively exposes OpenAPI JSON at the JHipster-standard <code>/v3/api-docs</code> endpoint. Features a completely re-engineered, glassmorphism Swagger UI deeply integrated with Keycloak SSO and automatic token refreshing.</p>
+                    <div class="flex gap-3">
+                        <span class="px-4 py-1.5 bg-amber-100 text-amber-700 text-[9px] font-black rounded-lg">JHIPSTER COMPATIBLE</span>
+                        <span class="px-4 py-1.5 bg-amber-100 text-amber-700 text-[9px] font-black rounded-lg">KEYCLOAK SSO UI</span>
+                    </div>
+                </div>
+
                 <div class="lg:col-span-12 bg-white p-10 rounded-[2.5rem] border border-fuchsia-100 shadow-sm hover:shadow-2xl transition-all group relative overflow-hidden cursor-crosshair bg-gradient-to-br from-white to-fuchsia-50/30">
                     <p class="text-[9px] font-bold text-fuchsia-600 uppercase tracking-widest mb-4">Elite Extension (+12%)</p>
                     <h4 class="text-2xl font-black text-slate-900 mb-3 tracking-tight italic">K8s Network Isolation & NodePorts</h4>
@@ -436,7 +446,7 @@
                 </div>
 
             <div class="mt-24 text-slate-500 font-mono text-[10px] uppercase tracking-[0.6em] font-black relative z-10">
-                GO-DUCK &bull; THE 395% ELITE MILESTONE &bull; SOVEREIGN CODE ORCHESTRATION
+                GO-DUCK &bull; THE 420% ELITE MILESTONE &bull; SOVEREIGN CODE ORCHESTRATION
             </div>
         </div>
     </section>

package/templates/docs/pages/integrations.hbs

@@ -86,8 +86,13 @@ class ApiProvider {
     <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">3. WSO2 API Manager Integration</h2>
     <p class="mb-4">GO-DUCK generated APIs can automatically register themselves with a <strong>WSO2 API Manager</strong> instance on startup. This uses the WSO2 Publisher REST API to import your dynamically generated OpenAPI 3.0 specs.</p>
     
+    <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
+        <h4 class="font-bold text-indigo-900 mb-1">Standard API Gateway Discovery</h4>
+        <p class="text-sm text-indigo-800">For external gateways (Kong, Apigee) and ecosystems like <strong>JHipster</strong> and <strong>Spring Boot</strong>, your microservice natively exposes its OpenAPI JSON at the standard <code>/v3/api-docs</code> endpoint. Legacy systems can still use <code>/swagger.json</code>.</p>
+    </div>
+
     <div class="bg-blue-50 border-l-4 border-blue-500 p-4 mb-6 rounded-r">
-        <p class="text-blue-900"><strong>Configuration:</strong> Enable this by adding the <code>wso2</code> block to your <code>config.yaml</code>.</p>
+        <p class="text-blue-900"><strong>WSO2 Configuration:</strong> Enable this by adding the <code>wso2</code> block to your <code>config.yaml</code>.</p>
     </div>
 
     <pre><code class="language-yaml">go-duck:

package/templates/docs/pages/mosquitto.hbs

@@ -29,6 +29,12 @@ messaging.Publish("events/users", event)</code></pre>
 mosquitto_sub -h localhost -p {{mqttPort}} -t "audit/logs/#" -v</code></pre>
 </section>
 
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Interactive Swagger Console</h2>
+    <p class="mb-4">GO-DUCK's automatically generated Swagger UI features a built-in <strong>Interactive MQTT Topics Dictionary</strong>. By connecting via WebSockets, it allows authenticated users to dynamically <strong>SUBSCRIBE</strong> to event streams or <strong>PUBLISH</strong> payloads directly from the documentation interface!</p>
+    <p class="mb-4 text-sm text-gray-600 italic">Note: Ensure your Mosquitto broker is configured to accept WebSocket connections (default port 9001) for this feature to work.</p>
+</section>
+
 <section class="mb-10">
     <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">External Resources</h2>
     <ul class="space-y-2">

package/templates/go/router.go.hbs

@@ -5,6 +5,7 @@ import (
     "fmt"
     "log"
     "net/http"
+    "strings"
     "time"
 
     "github.com/gin-gonic/gin"
@@ -162,41 +163,492 @@ func SetupRouter(appConfig *config.Config) *gin.Engine {
     })
 
     // Swagger Docs & UI
-    r.StaticFile("/swagger.json", "./docs/swagger.json")
+    // Expose standard OpenAPI endpoints (JHipster / Spring / WSO2 compatibility)
+    r.StaticFile("/v3/api-docs", "./docs/swagger.json")
+    r.StaticFile("/swagger.json", "./docs/swagger.json") // Legacy fallback
+    r.StaticFile("/api/mqtt-topics", "./docs/mqtt_topics.json5")
+    r.StaticFile("/logo.png", "./docs/web/logo.png")
     r.GET("/swagger", func(c *gin.Context) {
-        c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(`<!DOCTYPE html>
+        swaggerHTML := `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <title>Swagger UI</title>
+  <title>Swagger UI (Secured)</title>
   <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui.css" />
+  <script src="https://cdn.jsdelivr.net/npm/keycloak-js@24.0.4/dist/keycloak.min.js"></script>
+  <script src="https://unpkg.com/mqtt/dist/mqtt.min.js"></script>
   <style>
     html { box-sizing: border-box; overflow: -moz-scrollbars-vertical; overflow-y: scroll; }
     *, *:before, *:after { box-sizing: inherit; }
-    body { margin:0; background: #fafafa; }
+    body { margin:0; background: #fafafa; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
+    
+    .top-nav {
+      background: rgba(255, 255, 255, 0.8);
+      backdrop-filter: blur(10px);
+      -webkit-backdrop-filter: blur(10px);
+      border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+      padding: 12px 24px;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      position: sticky;
+      top: 0;
+      z-index: 1000;
+      box-shadow: 0 4px 6px -1px rgba(0,0,0,0.05);
+    }
+
+    .nav-brand {
+      font-weight: 700;
+      font-size: 1.2rem;
+      color: #333;
+      display: flex;
+      align-items: center;
+      gap: 10px;
+    }
+
+    .nav-controls {
+      display: flex;
+      align-items: center;
+      gap: 16px;
+    }
+
+    .tenant-input {
+      padding: 8px 12px;
+      border: 1px solid #ddd;
+      border-radius: 6px;
+      font-size: 0.9rem;
+      outline: none;
+      transition: border-color 0.2s;
+    }
+    
+    .tenant-input:focus {
+      border-color: #4a90e2;
+    }
+
+    .btn {
+      padding: 8px 16px;
+      border-radius: 6px;
+      border: none;
+      font-weight: 600;
+      cursor: pointer;
+      transition: all 0.2s;
+      font-size: 0.9rem;
+    }
+
+    .btn-login {
+      background: #4a90e2;
+      color: white;
+    }
+
+    .btn-login:hover {
+      background: #357abd;
+    }
+
+    .btn-logout {
+      background: #e74c3c;
+      color: white;
+      display: none;
+    }
+
+    .btn-logout:hover {
+      background: #c0392b;
+    }
+
+    .status-indicator {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      font-size: 0.85rem;
+      color: #666;
+    }
+
+    .dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: #ccc;
+    }
+
+    .dot.active {
+      background: #2ecc71;
+      box-shadow: 0 0 8px #2ecc71;
+    }
+
+    /* MQTT Topics Viewer */
+    #mqtt-modal {
+      display: none;
+      position: fixed;
+      top: 0; left: 0; width: 100%; height: 100%;
+      background: rgba(0,0,0,0.6);
+      z-index: 2000;
+      justify-content: center;
+      align-items: center;
+    }
+    .mqtt-content {
+      background: #000;
+      width: 80%; max-width: 900px;
+      border-radius: 8px;
+      padding: 20px;
+      color: #00ff00;
+      font-family: monospace;
+      position: relative;
+      box-shadow: 0 10px 25px rgba(0,0,0,0.5);
+    }
+    .mqtt-header {
+      display: flex;
+      justify-content: space-between;
+      margin-bottom: 10px;
+      border-bottom: 1px solid #333;
+      padding-bottom: 10px;
+    }
+    .mqtt-close { color: white; cursor: pointer; font-size: 1.5rem; }
+    .mqtt-dl { background: #333; color: white; border: none; padding: 5px 10px; cursor: pointer; border-radius: 4px; }
+    .mqtt-dl:hover { background: #555; }
+    
+    .syntax-punct { color: #ff0000; }
+    
+    /* Interactive MQTT Actions */
+    .mqtt-action-btn {
+      margin-left: 10px; padding: 2px 8px; border: none; border-radius: 4px;
+      font-size: 0.8rem; font-weight: bold; color: white; cursor: pointer;
+      vertical-align: middle;
+    }
+    #mqtt-action-modal {
+      display: none; position: fixed; top: 0; left: 0; width: 100%; height: 100%;
+      background: rgba(0,0,0,0.8); z-index: 3000; justify-content: center; align-items: center;
+    }
+    .mqtt-action-content {
+      background: #1e1e1e; width: 80%; max-width: 800px; border-radius: 8px; padding: 20px;
+      color: #fff; font-family: monospace; position: relative;
+    }
+    .mqtt-console {
+      background: #000; color: #0f0; padding: 10px; height: 300px; overflow-y: auto;
+      border-radius: 4px; margin-top: 10px; border: 1px solid #333; white-space: pre-wrap;
+    }
+    .mqtt-editor {
+      width: 100%; height: 200px; background: #000; color: #0f0; font-family: monospace;
+      padding: 10px; border: 1px solid #333; border-radius: 4px; margin-top: 10px;
+    }
+    .broker-input {
+      background: #333; color: #fff; border: 1px solid #555; padding: 5px;
+      border-radius: 4px; width: 250px; margin-left: 15px; font-family: monospace;
+    }
   </style>
 </head>
 <body>
+  <div class="top-nav">
+    <div class="nav-brand">
+      <img src="/logo.png" alt="GO-DUCK Logo" style="height: 32px; width: auto;" />
+      <div style="display: flex; flex-direction: column; line-height: 1.2;">
+        <span>{{app_name}} API Explorer</span>
+        <span style="font-size: 0.65em; font-weight: normal; color: #94a3b8;">
+          GO-DUCK v{{cli_version}} • Generated: {{generated_date}}
+        </span>
+      </div>
+    </div>
+    <div class="nav-controls">
+      <div class="status-indicator">
+        <div class="dot" id="auth-dot"></div>
+        <span id="auth-status">Unauthenticated</span>
+      </div>
+      <input type="text" id="tenant-input" class="tenant-input" placeholder="X-Tenant-ID" value="tenant_1" title="Multi-tenant DB Target" />
+      <button id="login-btn" class="btn btn-login">Login with Keycloak</button>
+      <button id="logout-btn" class="btn btn-logout">Logout</button>
+      <button id="mqtt-btn" class="btn" style="background: #2c3e50; color: white;">MQTT Topics</button>
+    </div>
+  </div>
+
   <div id="swagger-ui"></div>
+  
+  <div id="mqtt-modal">
+    <div class="mqtt-content">
+      <div class="mqtt-header">
+        <h3 style="margin: 0; color: white;">MQTT Topics Dictionary (JSON5)</h3>
+        <div>
+          <button class="mqtt-dl" id="mqtt-dl-btn">Download JSON5</button>
+          <span class="mqtt-close" id="mqtt-close">&times;</span>
+        </div>
+      </div>
+      <pre id="mqtt-viewer" style="overflow-x: auto; max-height: 70vh; margin: 0;"></pre>
+    </div>
+  </div>
+
+  <div id="mqtt-action-modal">
+    <div class="mqtt-action-content">
+      <div style="display: flex; justify-content: space-between; border-bottom: 1px solid #333; padding-bottom: 10px;">
+        <div>
+          <h3 style="margin: 0; display: inline-block;"><span id="action-title">SUBSCRIBE</span>: <span id="action-topic" style="color: #3498db;"></span></h3>
+          <input type="text" id="broker-url" class="broker-input" value="ws://localhost:9001" title="Broker WS URL" />
+          <span id="broker-status" style="margin-left: 10px; font-size: 0.9rem; color: #f39c12;">Disconnected</span>
+        </div>
+        <span class="mqtt-close" id="mqtt-action-close">&times;</span>
+      </div>
+      
+      <!-- Subscribe View -->
+      <div id="view-subscribe" style="display: none;">
+        <div class="mqtt-console" id="mqtt-console">Waiting for messages...\n</div>
+      </div>
+      
+      <!-- Publish View -->
+      <div id="view-publish" style="display: none;">
+        <textarea id="mqtt-payload" class="mqtt-editor">{\n  "example": "payload"\n}</textarea>
+        <button id="mqtt-publish-btn" class="btn" style="background: #e74c3c; color: white; margin-top: 15px; width: 100%;">PUBLISH PAYLOAD</button>
+      </div>
+    </div>
+  </div>
+
   <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-bundle.js"></script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-standalone-preset.js"></script>
   <script>
+    const KEYCLOAK_URL = 'KEYCLOAK_URL_PLACEHOLDER';
+    const KEYCLOAK_REALM = 'KEYCLOAK_REALM_PLACEHOLDER';
+    const KEYCLOAK_CLIENT = 'KEYCLOAK_CLIENT_PLACEHOLDER';
+
+    let keycloak = null;
+
+    function updateUI(authenticated) {
+      if (authenticated) {
+        document.getElementById('login-btn').style.display = 'none';
+        document.getElementById('logout-btn').style.display = 'block';
+        document.getElementById('auth-dot').classList.add('active');
+        document.getElementById('auth-status').innerText = 'Authenticated (' + (keycloak.tokenParsed?.preferred_username || 'User') + ')';
+      } else {
+        document.getElementById('login-btn').style.display = 'block';
+        document.getElementById('logout-btn').style.display = 'none';
+        document.getElementById('auth-dot').classList.remove('active');
+        document.getElementById('auth-status').innerText = 'Unauthenticated';
+      }
+    }
+
     window.onload = function() {
-      const ui = SwaggerUIBundle({
-        url: "/swagger.json",
-        dom_id: '#swagger-ui',
-        deepLinking: true,
-        presets: [
-          SwaggerUIBundle.presets.apis,
-          SwaggerUIStandalonePreset
-        ],
-        layout: "StandaloneLayout"
+      // Initialize Keycloak
+      keycloak = new Keycloak({
+        url: KEYCLOAK_URL,
+        realm: KEYCLOAK_REALM,
+        clientId: KEYCLOAK_CLIENT
+      });
+
+      keycloak.init({ onLoad: 'check-sso', checkLoginIframe: false }).then(authenticated => {
+        updateUI(authenticated);
+
+        document.getElementById('login-btn').onclick = () => keycloak.login();
+        document.getElementById('logout-btn').onclick = () => keycloak.logout();
+
+        if (authenticated) {
+          // Auto-refresh token logic
+          setInterval(() => {
+            keycloak.updateToken(70).then(refreshed => {
+              if (refreshed) {
+                console.log('Token refreshed automatically');
+              }
+            }).catch(() => {
+              console.error('Failed to refresh token');
+              updateUI(false);
+            });
+          }, 60000); // Check every minute
+        }
+
+        // 4. Initialize Swagger UI
+        const ui = SwaggerUIBundle({
+          url: "/v3/api-docs",
+          dom_id: '#swagger-ui',
+          deepLinking: true,
+          presets: [
+            SwaggerUIBundle.presets.apis,
+            SwaggerUIStandalonePreset
+          ],
+          layout: "StandaloneLayout",
+          requestInterceptor: (req) => {
+            if (keycloak && keycloak.token) {
+              req.headers['Authorization'] = 'Bearer ' + keycloak.token;
+            }
+            const tenantId = document.getElementById('tenant-input').value;
+            if (tenantId) {
+              req.headers['X-Tenant-ID'] = tenantId;
+            }
+            return req;
+          }
+        });
+      }).catch(err => {
+        console.error("Keycloak initialization failed", err);
+        document.getElementById('auth-status').innerText = 'Keycloak init failed';
+        
+        // Still load swagger without auth interceptor
+        window.ui = SwaggerUIBundle({
+          url: "/v3/api-docs",
+          dom_id: '#swagger-ui',
+          deepLinking: true,
+          presets: [
+            SwaggerUIBundle.presets.apis,
+            SwaggerUIStandalonePreset
+          ],
+          layout: "StandaloneLayout"
+        });
       });
-      window.ui = ui;
+
+      // MQTT Viewer Logic
+      const mqttModal = document.getElementById('mqtt-modal');
+      const actionModal = document.getElementById('mqtt-action-modal');
+      const actionTitle = document.getElementById('action-title');
+      const actionTopic = document.getElementById('action-topic');
+      const viewSub = document.getElementById('view-subscribe');
+      const viewPub = document.getElementById('view-publish');
+      const brokerInput = document.getElementById('broker-url');
+      const brokerStatus = document.getElementById('broker-status');
+      const mqttConsole = document.getElementById('mqtt-console');
+      const payloadEditor = document.getElementById('mqtt-payload');
+      
+      let rawJson5 = '';
+      let mqttClient = null;
+      let currentTopic = '';
+      
+      // Open Action Modal Logic (Global so inline onClick can call it)
+      window.openMqttAction = function(topic, action) {
+        currentTopic = topic;
+        actionTitle.innerText = action;
+        actionTopic.innerText = topic;
+        
+        if (action === 'SEND') {
+          viewSub.style.display = 'none';
+          viewPub.style.display = 'block';
+        } else {
+          viewSub.style.display = 'block';
+          viewPub.style.display = 'none';
+          mqttConsole.innerHTML = `Waiting for messages on ${topic}...\\n`;
+        }
+        
+        actionModal.style.display = 'flex';
+        connectMqtt();
+      };
+      
+      function connectMqtt() {
+        if (mqttClient) {
+          if (mqttClient.options.href === brokerInput.value && mqttClient.connected) {
+             // Already connected to this broker, just subscribe if needed
+             if (actionTitle.innerText === 'SUBSCRIBE') mqttClient.subscribe(currentTopic);
+             return;
+          }
+          mqttClient.end();
+        }
+        
+        brokerStatus.innerText = "Connecting...";
+        brokerStatus.style.color = "#f39c12";
+        
+        try {
+          mqttClient = mqtt.connect(brokerInput.value);
+        } catch(e) {
+          brokerStatus.innerText = "Error: " + e.message;
+          brokerStatus.style.color = "#e74c3c";
+          return;
+        }
+        
+        mqttClient.on('connect', () => {
+          brokerStatus.innerText = "Connected";
+          brokerStatus.style.color = "#2ecc71";
+          if (actionTitle.innerText === 'SUBSCRIBE') {
+            mqttClient.subscribe(currentTopic, (err) => {
+              if(!err) mqttConsole.innerHTML += `Subscribed to ${currentTopic}\\n`;
+            });
+          }
+        });
+        
+        mqttClient.on('message', (topic, message) => {
+          if (topic === currentTopic) {
+            const time = new Date().toLocaleTimeString();
+            let msgStr = message.toString();
+            try { msgStr = JSON.stringify(JSON.parse(msgStr), null, 2); } catch(e){}
+            mqttConsole.innerHTML += `\\n<span style="color:#888">[${time}]</span>\\n${msgStr}\\n`;
+            mqttConsole.scrollTop = mqttConsole.scrollHeight;
+          }
+        });
+        
+        mqttClient.on('error', (err) => {
+          brokerStatus.innerText = "Error";
+          brokerStatus.style.color = "#e74c3c";
+          console.error("MQTT Error:", err);
+        });
+      }
+      
+      brokerInput.addEventListener('change', connectMqtt);
+      
+      document.getElementById('mqtt-publish-btn').onclick = () => {
+        if (!mqttClient || !mqttClient.connected) {
+          alert("Broker not connected!");
+          return;
+        }
+        const payload = payloadEditor.value;
+        mqttClient.publish(currentTopic, payload, {}, (err) => {
+          if (err) {
+            alert("Failed to publish: " + err);
+          } else {
+            alert("Message published to " + currentTopic);
+            actionModal.style.display = 'none';
+          }
+        });
+      };
+      
+      document.getElementById('mqtt-action-close').onclick = () => {
+        if (mqttClient && actionTitle.innerText === 'SUBSCRIBE') {
+          mqttClient.unsubscribe(currentTopic);
+        }
+        actionModal.style.display = 'none';
+      };
+      
+      document.getElementById('mqtt-btn').onclick = () => {
+        fetch('/api/mqtt-topics')
+          .then(res => {
+            if (!res.ok) throw new Error("Status " + res.status);
+            return res.text();
+          })
+          .then(text => {
+            rawJson5 = text;
+            let highlighted = text
+              .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+              .replace(/([{}[\]:,])/g, '<span class="syntax-punct">$1</span>');
+              
+            // Inject buttons next to topics (Only if authenticated)
+            highlighted = highlighted.replace(/"([^"]+)"(<span class="syntax-punct">.*?<\\/span>)/g, (match, topic, punct) => {
+              if (topic.includes('/')) {
+                let btnHtml = "";
+                if (keycloak && keycloak.authenticated) {
+                  const isSend = /patch|put|post|create|update/i.test(topic);
+                  const btnLabel = isSend ? "SEND" : "SUBSCRIBE";
+                  const btnColor = isSend ? "#e74c3c" : "#3498db";
+                  btnHtml = ` <button class="mqtt-action-btn" style="background:${btnColor}" onclick="openMqttAction('${topic}', '${btnLabel}')">${btnLabel}</button>`;
+                }
+                return `"${topic}"${punct}${btnHtml}`;
+              }
+              return match;
+            });
+              
+            document.getElementById('mqtt-viewer').innerHTML = highlighted;
+            mqttModal.style.display = 'flex';
+          }).catch(err => alert('Failed to fetch MQTT topics: ' + err));
+      };
+
+      document.getElementById('mqtt-close').onclick = () => mqttModal.style.display = 'none';
+      
+      document.getElementById('mqtt-dl-btn').onclick = () => {
+        const blob = new Blob([rawJson5], { type: 'application/json5' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = 'mqtt_topics.json5';
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+      };
     };
   </script>
 </body>
-</html>`))
+</html>`
+
+        htmlStr := strings.ReplaceAll(swaggerHTML, "KEYCLOAK_URL_PLACEHOLDER", appConfig.GoDuck.Security.KeycloakHost)
+        htmlStr = strings.ReplaceAll(htmlStr, "KEYCLOAK_REALM_PLACEHOLDER", appConfig.GoDuck.Security.KeycloakRealm)
+        htmlStr = strings.ReplaceAll(htmlStr, "KEYCLOAK_CLIENT_PLACEHOLDER", appConfig.GoDuck.Security.KeycloakAppClientID)
+
+        c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(htmlStr))
     })
 
     // Management APIs (Run-time DB onboarding)