create-skweb 1.1.5 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-skweb",
-  "version": "1.1.5",
+  "version": "2.1.0",
   "description": "Create a new SKWeb project with TypeScript, CJS, or MJS support",
   "type": "module",
   "main": "dist/index.cjs",
@@ -13,11 +13,14 @@
     "clean": "rm -rf dist",
     "clean:temp": "rm -rf .rollup.cache",
     "prebuild": "tsc --outDir dist --rootDir src",
-    "build": "rollup -c rollup.config.mjs && node scripts/inject-shebang.cjs && chmod +x dist/cli.cjs",
-    "build:dev": "rollup -c rollup.config.mjs --environment NODE_ENV:development && node scripts/inject-shebang.cjs && chmod +x dist/cli.cjs",
+    "build": "rollup -c rollup.config.mjs && node scripts/inject-shebang.mjs && chmod +x dist/cli.cjs",
+    "build:dev": "rollup -c rollup.config.mjs --environment NODE_ENV:development && node scripts/inject-shebang.mjs && chmod +x dist/cli.cjs",
     "lint": "eslint --fix --ext .ts src",
     "check": "tsc --noEmit",
-    "test": "mocha test/**/*.mjs"
+    "test": "mocha test/**/*.mjs",
+    "sync:versions": "node scripts/sync-template-versions.mjs",
+    "sync:versions:apply": "node scripts/sync-template-versions.mjs --apply",
+    "sync:versions:strict": "node scripts/sync-template-versions.mjs --strict"
   },
   "dependencies": {
     "commander": "^12.1.0",

package/scripts/inject-shebang.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+//
+// inject-shebang.mjs
+//
+// 给 rollup 产出的 CLI 文件加 shebang。
+// rollup 在某些场景下会丢失或重复 shebang（特别是使用 @rollup/plugin-replace
+// 替换 /usr/bin/env 时），这里统一收口。
+//
+// 用法：
+//   node scripts/inject-shebang.mjs                # 默认 ./dist/cli.cjs
+//   node scripts/inject-shebang.mjs dist/cli.cjs   # 相对 cwd 的目标
+//   node scripts/inject-shebang.mjs /abs/path/cli  # 绝对路径
+//
+// 说明：
+//   - 已存在 shebang 时跳过，不重复添加
+//   - 文件不存在时给出明确错误信息（避免静默失败）
+//
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const SHEBANG = '#!/usr/bin/env node\n'
+
+const arg = process.argv[2]
+const target = arg ? path.resolve(arg) : path.resolve('dist/cli.cjs')
+
+if (!fs.existsSync(target)) {
+  console.error(`[inject-shebang] target not found: ${target}`)
+  process.exit(1)
+}
+
+let content = fs.readFileSync(target, 'utf-8')
+if (content.startsWith('#!')) {
+  console.log(`[inject-shebang] Shebang already present in ${target}`)
+  process.exit(0)
+}
+
+fs.writeFileSync(target, SHEBANG + content, 'utf-8')
+console.log(`[inject-shebang] Shebang added to ${target}`)

package/scripts/sync-template-versions.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+//
+// sync-template-versions.mjs
+//
+// 把本工程 packages 下的 skweb-* 包版本号
+// 同步到 tools/create-skweb/templates 下的 package.json。
+//
+// 用法：
+//   node scripts/sync-template-versions.mjs            # 默认 dry-run，仅打印
+//   node scripts/sync-template-versions.mjs --apply    # 写回文件
+//   node scripts/sync-template-versions.mjs --strict   # 严格模式：发现不一致退出码 1
+//   node scripts/sync-template-versions.mjs --help     # 查看帮助
+//
+// 同步规则：
+//   - workspace 的 X.Y.Z 映射到模板的 ^X.Y.0
+//   - 仅修改 skweb-* 开头的依赖（其他依赖不动）
+//   - 仅处理 templates 目录下 .json 文件
+//
+// 退出码：
+//   0  全部一致，或已 --apply 写回
+//   1  --strict 模式下发现不一致且未 --apply
+//   2  执行过程异常
+//
+// 建议在以下时机执行：
+//   - 每次 changeset version 之后
+//   - 提交前
+//   - CI 发布前
+//
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const ROOT = path.join(__dirname, '..', '..', '..') // -> skweb-mono/
+const PACKAGES_DIR = path.join(ROOT, 'packages')
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates')
+
+// ANSI 颜色（仅在 TTY 启用，避免污染 CI 日志）
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR
+const color = (code) => (useColor ? `\x1b[${code}m` : '')
+const cBold = color('1')
+const cYellow = color('33')
+const cRed = color('31')
+const cGreen = color('32')
+const cCyan = color('36')
+const cReset = color('0')
+
+function showHelp() {
+  console.log(`${cBold}sync-template-versions${cReset}
+把 packages/ 下的 skweb-* 版本号同步到 templates/ 下的 package.json。
+
+${cBold}用法${cReset}
+  ${cCyan}node scripts/sync-template-versions.mjs${cReset}              ${cYellow}# 默认 dry-run${cReset}
+  ${cCyan}node scripts/sync-template-versions.mjs --apply${cReset}      # 写回文件
+  ${cCyan}node scripts/sync-template-versions.mjs --strict${cReset}     # 严格模式（CI 推荐）
+  ${cCyan}node scripts/sync-template-versions.mjs --help${cReset}       # 查看帮助
+
+${cBold}同步规则${cReset}
+  - workspace 的 X.Y.Z 映射到模板的 ^X.Y.0
+  - 仅修改 skweb-* 开头的依赖
+  - 仅处理 templates 目录下 *.json
+
+${cBold}退出码${cReset}
+  0  全部一致，或已 --apply 写回
+  1  --strict 模式下发现不一致且未 --apply
+  2  执行过程异常
+
+${cBold}同步规则说明${cReset}
+  使用 ${cCyan}--apply${cReset} 真正写入文件；不带 --apply 永远只打印，不会改动模板。`)
+}
+
+const APPLY = process.argv.includes('--apply')
+const STRICT = process.argv.includes('--strict')
+const HELP = process.argv.includes('--help') || process.argv.includes('-h')
+
+if (HELP) {
+  showHelp()
+  process.exit(0)
+}
+
+// 扫描 packages/ 下所有 package.json，返回 { 包名: 版本 } 映射。
+function loadWorkspaceVersions() {
+  const result = {}
+  if (!fs.existsSync(PACKAGES_DIR)) {
+    throw new Error(`packages dir not found: ${PACKAGES_DIR}`)
+  }
+  for (const dir of fs.readdirSync(PACKAGES_DIR)) {
+    const pkgJsonPath = path.join(PACKAGES_DIR, dir, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) continue
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'))
+    if (pkg.name && pkg.version) {
+      result[pkg.name] = pkg.version
+    }
+  }
+  return result
+}
+
+// 把 X.Y.Z 转换为 ^X.Y.0 范围，允许 minor/patch 升级。
+function toRange(version) {
+  const parts = version.split('.')
+  if (parts.length < 2) {
+    throw new Error(`unexpected version format: ${version}`)
+  }
+  return `^${parts[0]}.${parts[1]}.0`
+}
+
+// 同步单个模板文件，返回变更列表。
+function syncTemplate(templatePath, workspaceVersions) {
+  const raw = fs.readFileSync(templatePath, 'utf-8')
+  const pkg = JSON.parse(raw)
+  const deps = pkg.dependencies || {}
+  const changes = []
+
+  for (const depName of Object.keys(deps)) {
+    if (!depName.startsWith('skweb-')) continue
+    if (!workspaceVersions[depName]) continue
+    const newRange = toRange(workspaceVersions[depName])
+    const oldRange = deps[depName]
+    if (oldRange !== newRange) {
+      changes.push({ dep: depName, old: oldRange, new: newRange })
+      deps[depName] = newRange
+    }
+  }
+
+  if (changes.length > 0 && APPLY) {
+    const updated = JSON.stringify(pkg, null, 2) + '\n'
+    fs.writeFileSync(templatePath, updated, 'utf-8')
+  }
+
+  return changes
+}
+
+function main() {
+  // 在最顶部打印运行模式，避免用户漏看后续信息
+  if (APPLY) {
+    console.log(`${cGreen}[sync] mode: APPLY (will write to files)${cReset}`)
+  } else {
+    console.log(`${cYellow}[sync] mode: DRY-RUN (no files will be modified; pass --apply to write)${cReset}`)
+  }
+  if (STRICT) {
+    console.log(`${cYellow}[sync] mode: STRICT (will exit 1 on pending changes)${cReset}`)
+  }
+  console.log('')
+
+  const workspaceVersions = loadWorkspaceVersions()
+  console.log(`[sync] workspace versions: ${Object.keys(workspaceVersions).length} packages`)
+  for (const [name, ver] of Object.entries(workspaceVersions)) {
+    console.log(`  ${name}: ${ver} -> ${toRange(ver)}`)
+  }
+  console.log('')
+
+  if (!fs.existsSync(TEMPLATES_DIR)) {
+    throw new Error(`templates dir not found: ${TEMPLATES_DIR}`)
+  }
+
+  let totalChanges = 0
+  const templateDirs = fs.readdirSync(TEMPLATES_DIR).filter(d => {
+    const full = path.join(TEMPLATES_DIR, d)
+    return fs.statSync(full).isDirectory()
+  })
+
+  for (const tpl of templateDirs) {
+    const pkgJson = path.join(TEMPLATES_DIR, tpl, 'package.json')
+    if (!fs.existsSync(pkgJson)) continue
+    const changes = syncTemplate(pkgJson, workspaceVersions)
+    if (changes.length === 0) {
+      console.log(`[sync] ${tpl}/package.json: in sync`)
+    } else {
+      totalChanges += changes.length
+      const tag = APPLY ? `${cGreen}[APPLIED]${cReset}` : `${cYellow}[dry-run]${cReset}`
+      console.log(`[sync] ${tpl}/package.json: ${changes.length} update(s) ${tag}`)
+      for (const c of changes) {
+        console.log(`    ${c.dep}: ${c.old} -> ${c.new}`)
+      }
+    }
+  }
+
+  console.log('')
+  if (totalChanges === 0) {
+    console.log(`${cGreen}[sync] All templates are in sync with workspace versions.${cReset}`)
+  } else if (APPLY) {
+    console.log(`${cGreen}[sync] Applied ${totalChanges} update(s).${cReset}`)
+  } else {
+    console.log(
+      `${cYellow}[sync] ${totalChanges} update(s) pending.${cReset} ` +
+      `${cBold}Re-run with ${cCyan}--apply${cReset}${cBold} to write.${cReset}`
+    )
+    if (STRICT) {
+      console.log(`${cRed}[sync] STRICT mode: exiting with code 1.${cReset}`)
+      process.exit(1)
+    }
+  }
+}
+
+try {
+  main()
+} catch (err) {
+  console.error('[sync] FAILED:', err.message)
+  process.exit(2)
+}

package/src/cli.ts

@@ -20,6 +20,7 @@ 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) => {
@@ -28,6 +29,7 @@ async function main() {
       // 只要没有传 --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')
 
@@ -35,6 +37,7 @@ async function main() {
       const needsPrompt = !name
         || !providedTemplate
         || !providedDest
+        || !providedAuth
         || !providedSkipInstall
         || !providedSkipGit
 
@@ -67,6 +70,18 @@ async function main() {
             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',
@@ -96,21 +111,23 @@ async function main() {
 
         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()
@@ -124,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

@@ -22,17 +22,19 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.71.0",
     "http-errors": "^2.0.0",
-    "skweb-express": "^1.0.0",
-    "skweb-express-jwt": "^1.0.0",
-    "skweb-express-logger": "^1.0.0",
-    "skweb-sequelize": "^1.0.0",
-    "skweb-redis": "^1.0.0",
-    "skweb-cron": "^1.0.0",
-    "skweb-framework": "^1.0.0",
-    "skweb-plugin": "^1.0.0",
-    "skweb-util": "^1.0.0",
+    "skweb-express": "^1.1.0",
+    "skweb-express-jwt": "^2.0.0",
+    "skweb-express-logger": "^1.1.0",
+    "skweb-sequelize": "^1.1.0",
+    "skweb-redis": "^1.1.0",
+    "skweb-cron": "^1.1.0",
+    "skweb-framework": "^1.1.0",
+    "skweb-plugin": "^1.1.0",
+    "skweb-util": "^1.1.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',