create-skweb 1.1.4 → 2.0.0

package/dist/index.js

@@ -6,6 +6,7 @@ import { execSync } from 'child_process';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 async function createProject(options) {
     const { name, description = 'A SKWeb project', template, dest } = options;
+    const auth = options.auth ?? 'static';
     const templateDir = path.join(__dirname, '..', 'templates', template);
     const baseDir = path.resolve(dest);
     const targetDir = path.join(baseDir, name);
@@ -29,7 +30,8 @@ async function createProject(options) {
         let content = await fs.readFile(srcPath, 'utf-8');
         content = content
             .replace(/\{\{name\}\}/g, name)
-            .replace(/\{\{description\}\}/g, description);
+            .replace(/\{\{description\}\}/g, description)
+            .replace(/\{\{auth\}\}/g, auth);
         const destPath = path.join(targetDir, fileName);
         await fs.writeFile(destPath, content);
     }
@@ -73,20 +75,23 @@ function printSuccess(name, dest) {
 接下来可以执行:
 
   cd ${name}
-  
+
+  # 复制环境变量模板并按需修改
+  cp .env.example .env
+
   # 开发模式运行
   npm run start:dev
-  
+
   # 生产模式运行 (需要先构建)
   npm run build
   npm run start
-  
+
   # 查看日志
   npm run logs
-  
+
   # 停止服务
   npm run stop
-  
+
   # 重启服务
   npm run restart
 
@@ -95,6 +100,7 @@ function printSuccess(name, dest) {
   ✅ @dotenvx/dotenvx 环境变量管理
   ✅ PM2 进程管理
   ✅ SKWeb Express 集成
+  ✅ Keycloak/JWKS 鉴权 (可选)
   ✅ ESLint 代码检查
   ✅ Mocha 测试框架
 `);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAKA,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AASvD,eAAe,aAAa,CAAC,OAAsB,EAAA;AACxD,IAAA,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,OAAO,CAAA;AAEzE,IAAA,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAA;IACrE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAE1C,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE;AAClC,QAAA,IAAI,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;AAC5C,YAAA,MAAM,IAAI,KAAK,CAAC,QAAQ,SAAS,CAAA,IAAA,CAAM,CAAC,CAAA;SACzC;KACF;SAAM;AACL,QAAA,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;KAC3B;AAED,IAAA,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AAEhE,IAAA,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;AACxB,QAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAA;QAChD,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AAEpC,QAAA,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE;AACvB,YAAA,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAA;YAC/C,SAAQ;SACT;QAED,IAAI,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAEjD,QAAA,OAAO,GAAG,OAAO;AACd,aAAA,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC;AAC9B,aAAA,OAAO,CAAC,sBAAsB,EAAE,WAAW,CAAC,CAAA;QAE/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;QAC/C,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;KACtC;AAED,IAAA,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAA;AAC/C,CAAC;AAEM,eAAe,mBAAmB,CAAC,IAAY,EAAE,IAAa,EAAA;AACnE,IAAA,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjF,QAAQ,CAAC,aAAa,EAAE;AACtB,QAAA,GAAG,EAAE,SAAS;AACd,QAAA,KAAK,EAAE,SAAS;AACjB,KAAA,CAAC,CAAA;IAEF,QAAQ,CAAC,oBAAoB,EAAE;AAC7B,QAAA,GAAG,EAAE,SAAS;AACd,QAAA,KAAK,EAAE,SAAS;AACjB,KAAA,CAAC,CAAA;AACJ,CAAC;AAEM,eAAe,OAAO,CAAC,IAAY,EAAE,IAAa,EAAA;AACvD,IAAA,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjF,QAAQ,CAAC,UAAU,EAAE;AACnB,QAAA,GAAG,EAAE,SAAS;AACd,QAAA,KAAK,EAAE,SAAS;AACjB,KAAA,CAAC,CAAA;AACJ,CAAC;SAEe,WAAW,GAAA;IACzB,OAAO,CAAC,GAAG,CAAC,CAAA;;;;AAIb,CAAA,CAAC,CAAA;AACF,CAAC;AAEe,SAAA,YAAY,CAAC,IAAY,EAAE,IAAY,EAAA;AACrD,IAAA,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;IACvD,OAAO,CAAC,GAAG,CAAC,CAAA;;;;;QAKN,IAAI,CAAA;QACJ,WAAW,CAAA;;;;OAIZ,IAAI,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBV,CAAA,CAAC,CAAA;AACF;;;;"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-skweb",
-  "version": "1.1.4",
+  "version": "2.0.0",
   "description": "Create a new SKWeb project with TypeScript, CJS, or MJS support",
   "type": "module",
   "main": "dist/index.cjs",

package/src/cli.ts

@@ -20,14 +20,31 @@ async function main() {
     .argument('[name]', 'Project name')
     .option('--template <type>', 'Template type: ts, mjs, cjs', 'ts')
     .option('--dest <path>', 'Destination directory', '.')
+    .option('--auth <type>', 'Auth provider: static (HS256) or jwks (Keycloak/Auth0)', 'static')
     .option('--skip-install', 'Skip dependency installation')
     .option('--skip-git', 'Skip git initialization')
     .action(async (name, options) => {
       printBanner()
-      
-      if (!name) {
-        const answers = await inquirer.prompt([
-          {
+
+      // 只要没有传 --no-interactive 且任何一个关键参数缺失，就走交互式 prompt
+      const providedTemplate = process.argv.includes('--template')
+      const providedDest = process.argv.includes('--dest')
+      const providedAuth = process.argv.includes('--auth')
+      const providedSkipInstall = process.argv.includes('--skip-install')
+      const providedSkipGit = process.argv.includes('--skip-git')
+
+      // 如果有任何一个关键参数未通过命令行提供，就走交互式 prompt
+      const needsPrompt = !name
+        || !providedTemplate
+        || !providedDest
+        || !providedAuth
+        || !providedSkipInstall
+        || !providedSkipGit
+
+      if (needsPrompt) {
+        const questions: any[] = []
+        if (!name) {
+          questions.push({
             type: 'input',
             name: 'name',
             message: 'Enter project name:',
@@ -38,8 +55,10 @@ async function main() {
               }
               return true
             }
-          },
-          {
+          })
+        }
+        if (!providedTemplate) {
+          questions.push({
             type: 'list',
             name: 'template',
             message: 'Select project template:',
@@ -49,44 +68,66 @@ async function main() {
               { name: 'CommonJS (CJS)', value: 'cjs' }
             ],
             default: 'ts'
-          },
-          {
+          })
+        }
+        if (!providedAuth) {
+          questions.push({
+            type: 'list',
+            name: 'auth',
+            message: 'Select auth provider:',
+            choices: [
+              { name: 'Static (HS256 shared secret)', value: 'static' },
+              { name: 'JWKS (Keycloak / Auth0 / OIDC)', value: 'jwks' }
+            ],
+            default: 'static'
+          })
+        }
+        if (!providedDest) {
+          questions.push({
             type: 'input',
             name: 'dest',
             message: 'Enter destination directory:',
             default: '.'
-          },
-          {
+          })
+        }
+        if (!providedSkipInstall) {
+          questions.push({
             type: 'confirm',
             name: 'install',
             message: 'Install dependencies?',
             default: true
-          },
-          {
+          })
+        }
+        if (!providedSkipGit) {
+          questions.push({
             type: 'confirm',
             name: 'git',
             message: 'Initialize git repository?',
             default: true
-          }
-        ])
-        
-        name = answers.name
-        options.template = answers.template
-        options.dest = answers.dest
-        options.skipInstall = !answers.install
-        options.skipGit = !answers.git
+          })
+        }
+
+        const answers: any = await inquirer.prompt(questions)
+
+        if (answers.name) name = answers.name
+        if (answers.template) options.template = answers.template
+        if (answers.auth) options.auth = answers.auth
+        if (answers.dest) options.dest = answers.dest
+        if (typeof answers.install === 'boolean') options.skipInstall = !answers.install
+        if (typeof answers.git === 'boolean') options.skipGit = !answers.git
       }
-      
+
       const spinner = ora('Creating project...').start()
-      
+
       try {
         await createProject({
           name,
           template: options.template as 'ts' | 'mjs' | 'cjs',
-          dest: options.dest
+          dest: options.dest,
+          auth: (options.auth || 'static') as 'static' | 'jwks'
         })
         spinner.succeed('Project files created')
-        
+
         if (!options.skipInstall) {
           spinner.text = 'Installing dependencies...'
           spinner.start()
@@ -100,11 +141,11 @@ async function main() {
           await initGit(options.dest, name)
           spinner.succeed('Git repository initialized')
         }
-        
+
         spinner.stop()
-        
+
         printSuccess(name, options.dest)
-        
+
       } catch (error) {
         spinner.fail('Failed to create project')
         console.error(error)

package/src/index.ts

@@ -10,10 +10,13 @@ export interface CreateOptions {
   description?: string
   template: 'ts' | 'mjs' | 'cjs'
   dest: string
+  /** Auth provider: 'static' (HS256, default) or 'jwks' (Keycloak/Auth0) */
+  auth?: 'static' | 'jwks'
 }
 
 export async function createProject(options: CreateOptions): Promise<void> {
   const { name, description = 'A SKWeb project', template, dest } = options
+  const auth = options.auth ?? 'static'
 
   const templateDir = path.join(__dirname, '..', 'templates', template)
   const baseDir = path.resolve(dest)
@@ -44,6 +47,7 @@ export async function createProject(options: CreateOptions): Promise<void> {
     content = content
       .replace(/\{\{name\}\}/g, name)
       .replace(/\{\{description\}\}/g, description)
+      .replace(/\{\{auth\}\}/g, auth)
 
     const destPath = path.join(targetDir, fileName)
     await fs.writeFile(destPath, content)
@@ -96,20 +100,23 @@ export function printSuccess(name: string, dest: string): void {
 接下来可以执行:
 
   cd ${name}
-  
+
+  # 复制环境变量模板并按需修改
+  cp .env.example .env
+
   # 开发模式运行
   npm run start:dev
-  
+
   # 生产模式运行 (需要先构建)
   npm run build
   npm run start
-  
+
   # 查看日志
   npm run logs
-  
+
   # 停止服务
   npm run stop
-  
+
   # 重启服务
   npm run restart
 
@@ -118,6 +125,7 @@ export function printSuccess(name: string, dest: string): void {
   ✅ @dotenvx/dotenvx 环境变量管理
   ✅ PM2 进程管理
   ✅ SKWeb Express 集成
+  ✅ Keycloak/JWKS 鉴权 (可选)
   ✅ ESLint 代码检查
   ✅ Mocha 测试框架
 `)

package/templates/cjs/.env.example

@@ -0,0 +1,73 @@
+# ============================================
+# SKWeb Environment Variables Template
+# ============================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# Variables with default values can be omitted.
+# Variables marked [REQUIRED] must be set in production.
+
+# ---------- Node Environment ----------
+# Development | Production | Test
+NODE_ENV=development
+
+# ---------- Server ----------
+PORT=3000
+HOST=0.0.0.0
+
+# ---------- Database (MySQL / MariaDB) ----------
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASS=
+DB_NAME={{name}}
+DB_DIALECT=mysql
+DB_CHARSET=utf8mb4
+DEBUG_DB=false
+
+# ---------- Redis ----------
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# ---------- Swagger / OpenAPI ----------
+# Mounts Swagger UI at /api-docs and exposes raw spec at /api-docs.json.
+# Only enabled when NODE_ENV is 'development' or 'test'.
+# Set SWAGGER_ENABLED=false to force-disable in dev/test as well.
+# (Production is always disabled to avoid exposing internal API details.)
+SWAGGER_ENABLED=true
+
+# ---------- Auth Provider ----------
+# 'static' (default): use a shared secret (HS256)
+# 'jwks': verify via JWKS endpoint (Keycloak / Auth0 / generic OIDC)
+AUTH_PROVIDER={{auth}}
+
+# ---------- JWT (static mode) ----------
+# [REQUIRED in production] Use a strong random string, e.g. `openssl rand -hex 32`
+JWT_SECRET=please-change-this-in-production
+JWT_EXPIRES_IN=7d
+
+# ---------- JWT (jwks mode, OIDC compatible) ----------
+# Works with any OIDC-compliant IdP. Common issuer formats:
+#   Keycloak:  https://kc.example.com/realms/myrealm
+#   Auth0:     https://your-tenant.auth0.com/
+#   Okta:      https://your-domain.okta.com/oauth2/default
+#   Authing:   https://your-app.authing.cn/oauth2/default
+#   Keycloak Realm: https://kc.example.com/auth/realms/myrealm
+# `audience` is the client id of this API in the IdP (recommended).
+# JWKS URI is auto-derived as ${OIDC_ISSUER}/.well-known/jwks.json
+# unless OIDC_JWKS_URI is set explicitly.
+OIDC_ISSUER=
+OIDC_AUDIENCE=
+OIDC_JWKS_URI=
+
+# ---------- Logging ----------
+# error | warn | info | http | verbose | debug | silly
+LOG_LEVEL=info
+LOG_DIR=./logs
+LOG_CONSOLE=true
+
+# ---------- CORS ----------
+# Comma-separated origins, or * for all
+CORS_ORIGIN=*

package/templates/cjs/package.json

@@ -23,7 +23,7 @@
     "@dotenvx/dotenvx": "^1.71.0",
     "http-errors": "^2.0.0",
     "skweb-express": "^1.0.0",
-    "skweb-express-jwt": "^1.0.0",
+    "skweb-express-jwt": "^1.2.0",
     "skweb-express-logger": "^1.0.0",
     "skweb-sequelize": "^1.0.0",
     "skweb-redis": "^1.0.0",
@@ -32,7 +32,9 @@
     "skweb-plugin": "^1.0.0",
     "skweb-util": "^1.0.0",
     "winston": "^3.17.0",
-    "sequelize": "^6.37.7"
+    "sequelize": "^6.37.7",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1"
   },
   "devDependencies": {
     "chai": "^6.2.1",

package/templates/cjs/src/app.js

@@ -3,9 +3,55 @@ require('dotenv/config')
 const path = require('path')
 const express = require('skweb-express')
 const expressLogger = require('skweb-express-logger').default || require('skweb-express-logger')
+const swaggerUi = require('swagger-ui-express')
 const { WebFramework } = require('skweb-framework')
 const { logger } = require('./utils/logger.js')
 const { checkRequiredEnv } = require('./utils/config.js')
+const { buildOpenApiSpec } = require('./swagger.js')
+
+/**
+ * 构建 JWT 配置，支持两种模式：
+ *  - 'static' (默认)：使用共享密钥（HS256/HS384/HS512），适用于自签 token
+ *  - 'jwks'：通过 JWKS 端点动态获取公钥（RS256 等），适用于 Keycloak/Auth0 等 IdP
+ */
+function buildJwtOptions() {
+  const provider = process.env.AUTH_PROVIDER || 'static'
+
+  if (provider === 'jwks') {
+    const issuer = process.env.OIDC_ISSUER
+    const jwksUri = process.env.OIDC_JWKS_URI
+    const audience = process.env.OIDC_AUDIENCE
+    if (!issuer && !jwksUri) {
+      throw new Error('AUTH_PROVIDER=jwks requires OIDC_ISSUER or OIDC_JWKS_URI')
+    }
+    return {
+      provider: 'jwks',
+      algorithms: ['RS256'],
+      jwks: { jwksUri, issuer, audience },
+      verify: { issuer, audience },
+      requestProperty: 'resolvedToken'
+    }
+  }
+
+  return {
+    provider: 'static',
+    secret: process.env.JWT_SECRET || 'please-change-this-in-production',
+    algorithms: ['HS256'],
+    sign: { expiresIn: process.env.JWT_EXPIRES_IN || '7d' },
+    requestProperty: 'resolvedToken'
+  }
+}
+
+/**
+ * Swagger UI 仅在 NODE_ENV 为 development / test，且 SWAGGER_ENABLED !== 'false' 时启用。
+ * 生产环境（production / unset）默认禁用，避免暴露内部 API 细节。
+ */
+function shouldEnableSwagger() {
+  const env = (process.env.NODE_ENV || '').toLowerCase()
+  if (env !== 'development' && env !== 'test') return false
+  if ((process.env.SWAGGER_ENABLED || '').toLowerCase() === 'false') return false
+  return true
+}
 
 async function bootstrap() {
   logger.info('[app] Initializing web process...')
@@ -50,17 +96,33 @@ async function bootstrap() {
   app.setOkCode(0)
   app.setOkMessage('success')
 
-  app.setJWT('default', {
-    secret: process.env.JWT_SECRET || 'please-change-this-in-production',
-    algorithms: ['HS256'],
-    sign: { expiresIn: process.env.JWT_EXPIRES_IN || '7d' },
-    requestProperty: 'resolvedToken'
-  })
+  // JWT 配置（按 AUTH_PROVIDER 选择 static 或 jwks 模式）
+  const jwtOptions = buildJwtOptions()
+  app.setJWT('default', jwtOptions)
   app.setJwtHintHeader('JwtHint')
 
+  if (jwtOptions.provider === 'jwks') {
+    logger.info(`[app] JWT auth provider: jwks (issuer: ${jwtOptions.jwks.issuer || jwtOptions.jwks.jwksUri})`)
+  } else {
+    logger.info('[app] JWT auth provider: static (HS256)')
+  }
+
   app.use(expressLogger())
   app.use(express.static(path.join(__dirname, '..', 'public')))
 
+  // 仅在 dev / test 环境挂载 Swagger UI（默认关闭，需显式 SWAGGER_ENABLED=true）
+  if (shouldEnableSwagger()) {
+    const openapiSpec = buildOpenApiSpec()
+    app.get('/api-docs.json', (_req, res) => res.json(openapiSpec))
+    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openapiSpec, {
+      customSiteTitle: `${process.env.APP_NAME || 'SKWeb'} API Docs`,
+      swaggerOptions: { persistAuthorization: true }
+    }))
+    logger.info(`[app] Swagger UI mounted at http://localhost:${process.env.PORT || 3000}/api-docs (env: ${process.env.NODE_ENV})`)
+  } else {
+    logger.info(`[app] Swagger UI disabled (env: ${process.env.NODE_ENV || 'unset'})`)
+  }
+
   await framework.loadControllers(path.join(__dirname, './controllers'))
   await framework.loadPluginControllers()
 
@@ -88,4 +150,4 @@ if (require.main === module) {
   })
 }
 
-module.exports = { bootstrap }
+module.exports = { bootstrap }

package/templates/cjs/src/controllers/hello.js

@@ -1,3 +1,49 @@
+/**
+ * @swagger
+ * /:
+ *   get:
+ *     summary: 欢迎页
+ *     description: 返回项目基本信息。
+ *     tags: [Hello]
+ *     responses:
+ *       200:
+ *         description: OK
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message: { type: string, example: 'Welcome to SKWeb!' }
+ *                 version: { type: string, example: '1.0.0' }
+ *                 timestamp: { type: string, format: date-time }
+ * /health:
+ *   get:
+ *     summary: 健康检查
+ *     tags: [Hello]
+ *     responses:
+ *       200:
+ *         description: OK
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status: { type: string, example: 'ok' }
+ *                 timestamp: { type: string, format: date-time }
+ * /echo:
+ *   post:
+ *     summary: 回显请求体
+ *     tags: [Hello]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *     responses:
+ *       200:
+ *         description: OK
+ */
 module.exports = [
   {
     method: 'get',

package/templates/cjs/src/swagger.js

@@ -0,0 +1,52 @@
+'use strict'
+
+const path = require('path')
+const swaggerJSDoc = require('swagger-jsdoc')
+
+/**
+ * 构建 OpenAPI 3.0 规范对象。
+ *
+ * 控制器中应使用 @swagger JSDoc 注释描述端点，例如：
+ *
+ *   /**
+ *    * @swagger
+ *    * /api/users:
+ *    *   get:
+ *    *     summary: 获取用户列表
+ *    *     tags: [Users]
+ *    *     responses:
+ *    *       200:
+ *    *         description: OK
+ *    *\/
+ */
+function buildOpenApiSpec() {
+  return swaggerJSDoc({
+    definition: {
+      openapi: '3.0.3',
+      info: {
+        title: process.env.APP_NAME || 'SKWeb API',
+        version: process.env.API_VERSION || '1.0.0',
+        description: process.env.APP_DESCRIPTION || 'SKWeb project API documentation',
+        contact: { name: 'API Support' }
+      },
+      servers: [
+        { url: `http://localhost:${process.env.PORT || 3000}`, description: 'Local development' }
+      ],
+      components: {
+        securitySchemes: {
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+            description: 'Paste a JWT token here (only needed when AUTH_PROVIDER=static)'
+          }
+        }
+      }
+    },
+    apis: [
+      path.join(__dirname, 'controllers', '*.js')
+    ]
+  })
+}
+
+module.exports = { buildOpenApiSpec }

package/templates/mjs/.env.example

@@ -0,0 +1,73 @@
+# ============================================
+# SKWeb Environment Variables Template
+# ============================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# Variables with default values can be omitted.
+# Variables marked [REQUIRED] must be set in production.
+
+# ---------- Node Environment ----------
+# Development | Production | Test
+NODE_ENV=development
+
+# ---------- Server ----------
+PORT=3000
+HOST=0.0.0.0
+
+# ---------- Database (MySQL / MariaDB) ----------
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASS=
+DB_NAME={{name}}
+DB_DIALECT=mysql
+DB_CHARSET=utf8mb4
+DEBUG_DB=false
+
+# ---------- Redis ----------
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# ---------- Swagger / OpenAPI ----------
+# Mounts Swagger UI at /api-docs and exposes raw spec at /api-docs.json.
+# Only enabled when NODE_ENV is 'development' or 'test'.
+# Set SWAGGER_ENABLED=false to force-disable in dev/test as well.
+# (Production is always disabled to avoid exposing internal API details.)
+SWAGGER_ENABLED=true
+
+# ---------- Auth Provider ----------
+# 'static' (default): use a shared secret (HS256)
+# 'jwks': verify via JWKS endpoint (Keycloak / Auth0 / generic OIDC)
+AUTH_PROVIDER={{auth}}
+
+# ---------- JWT (static mode) ----------
+# [REQUIRED in production] Use a strong random string, e.g. `openssl rand -hex 32`
+JWT_SECRET=please-change-this-in-production
+JWT_EXPIRES_IN=7d
+
+# ---------- JWT (jwks mode, OIDC compatible) ----------
+# Works with any OIDC-compliant IdP. Common issuer formats:
+#   Keycloak:  https://kc.example.com/realms/myrealm
+#   Auth0:     https://your-tenant.auth0.com/
+#   Okta:      https://your-domain.okta.com/oauth2/default
+#   Authing:   https://your-app.authing.cn/oauth2/default
+#   Keycloak Realm: https://kc.example.com/auth/realms/myrealm
+# `audience` is the client id of this API in the IdP (recommended).
+# JWKS URI is auto-derived as ${OIDC_ISSUER}/.well-known/jwks.json
+# unless OIDC_JWKS_URI is set explicitly.
+OIDC_ISSUER=
+OIDC_AUDIENCE=
+OIDC_JWKS_URI=
+
+# ---------- Logging ----------
+# error | warn | info | http | verbose | debug | silly
+LOG_LEVEL=info
+LOG_DIR=./logs
+LOG_CONSOLE=true
+
+# ---------- CORS ----------
+# Comma-separated origins, or * for all
+CORS_ORIGIN=*

package/templates/mjs/package.json

@@ -23,7 +23,7 @@
     "@dotenvx/dotenvx": "^1.71.0",
     "http-errors": "^2.0.0",
     "skweb-express": "^1.0.0",
-    "skweb-express-jwt": "^1.0.0",
+    "skweb-express-jwt": "^1.2.0",
     "skweb-express-logger": "^1.0.0",
     "skweb-sequelize": "^1.0.0",
     "skweb-redis": "^1.0.0",
@@ -32,7 +32,9 @@
     "skweb-plugin": "^1.0.0",
     "skweb-util": "^1.0.0",
     "winston": "^3.17.0",
-    "sequelize": "^6.37.7"
+    "sequelize": "^6.37.7",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1"
   },
   "devDependencies": {
     "chai": "^6.2.1",