create-skweb 1.1.5 → 2.0.0

package/templates/mjs/src/swagger.js

@@ -0,0 +1,52 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import swaggerJSDoc from 'swagger-jsdoc'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+/**
+ * 构建 OpenAPI 3.0 规范对象。
+ *
+ * 控制器中应使用 @swagger JSDoc 注释描述端点，例如：
+ *
+ *   /**
+ *    * @swagger
+ *    * /api/users:
+ *    *   get:
+ *    *     summary: 获取用户列表
+ *    *     tags: [Users]
+ *    *     responses:
+ *    *       200:
+ *    *         description: OK
+ *    *\/
+ */
+export 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')
+    ]
+  })
+}

package/templates/ts/.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/ts/package.json

@@ -25,7 +25,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",
@@ -34,12 +34,16 @@
     "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": {
     "@types/node": "^25.0.1",
     "@types/mocha": "^10.0.10",
     "@types/http-errors": "^2.0.4",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.8",
     "chai": "^6.2.1",
     "mocha": "^11.7.5",
     "tsx": "^4.22.4",

package/templates/ts/src/app.ts

@@ -5,12 +5,66 @@ import { fileURLToPath } from 'url'
 import express from 'skweb-express'
 import expressLogger from 'skweb-express-logger'
 import { WebFramework } from 'skweb-framework'
+import type { JWTOptions } from 'skweb-express-jwt'
+import swaggerUi from 'swagger-ui-express'
 import logger from './utils/logger.js'
 import { checkRequiredEnv } from './utils/config.js'
+import { buildOpenApiSpec } from './swagger.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
+/**
+ * 构建 JWT 配置，支持两种模式：
+ *  - 'static' (默认)：使用共享密钥（HS256/HS384/HS512），适用于自签 token
+ *  - 'jwks'：通过 JWKS 端点动态获取公钥（RS256 等），适用于 Keycloak/Auth0 等 IdP
+ */
+function buildJwtOptions(): JWTOptions {
+  const provider = (process.env.AUTH_PROVIDER || 'static') as 'static' | 'jwks'
+
+  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') as any },
+    requestProperty: 'resolvedToken'
+  }
+}
+
+/**
+ * Swagger UI 仅在 NODE_ENV 为 development / test，且 SWAGGER_ENABLED !== 'false' 时启用。
+ * 生产环境（production / unset）默认禁用，避免暴露内部 API 细节。
+ */
+function shouldEnableSwagger(): boolean {
+  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(): Promise<void> {
   logger.info('[app] Initializing web process...')
 
@@ -54,17 +108,33 @@ async function bootstrap(): Promise<void> {
   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 as any)
   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()
 
@@ -93,4 +163,4 @@ if (isMainModule) {
   })
 }
 
-export { bootstrap }
+export { bootstrap }

package/templates/ts/src/controllers/hello.ts

@@ -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
+ */
 export default [
   {
     method: 'get',

package/templates/ts/src/swagger.ts

@@ -0,0 +1,54 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import swaggerJSDoc from 'swagger-jsdoc'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+/**
+ * 构建 OpenAPI 3.0 规范对象。
+ *
+ * 控制器中应使用 @swagger JSDoc 注释描述端点，例如：
+ *
+ *   /**
+ *    * @swagger
+ *    * /api/users:
+ *    *   get:
+ *    *     summary: 获取用户列表
+ *    *     tags: [Users]
+ *    *     responses:
+ *    *       200:
+ *    *         description: OK
+ *    *\/
+ */
+export function buildOpenApiSpec(): object {
+  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)'
+          }
+        }
+      }
+    },
+    // 扫描 controllers 目录与 src 根下的 JSDoc 注释
+    apis: [
+      path.join(__dirname, 'controllers', '*.ts'),
+      path.join(__dirname, 'controllers', '*.js')
+    ]
+  })
+}