@dangao/bun-server 0.1.3 → 0.1.5

package/dist/swagger/swagger-module.d.ts

@@ -0,0 +1,37 @@
+import type { SwaggerOptions } from './types';
+/**
+ * Swagger 模块配置
+ */
+export interface SwaggerModuleOptions extends SwaggerOptions {
+    /**
+     * Swagger UI 路径
+     * @default '/swagger'
+     */
+    uiPath?: string;
+    /**
+     * Swagger JSON 路径
+     * @default '/swagger.json'
+     */
+    jsonPath?: string;
+    /**
+     * Swagger UI 标题
+     */
+    uiTitle?: string;
+    /**
+     * 是否启用 Swagger UI
+     * @default true
+     */
+    enableUI?: boolean;
+}
+/**
+ * Swagger 模块
+ * 提供 API 文档生成和 Swagger UI
+ */
+export declare class SwaggerModule {
+    /**
+     * 创建 Swagger 模块
+     * @param options - 模块配置
+     */
+    static forRoot(options: SwaggerModuleOptions): typeof SwaggerModule;
+}
+//# sourceMappingURL=swagger-module.d.ts.map

package/dist/swagger/swagger-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger-module.d.ts","sourceRoot":"","sources":["../../src/swagger/swagger-module.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,qBAQa,aAAa;IACxB;;;OAGG;WACW,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,aAAa;CAkC3E"}

package/dist/swagger/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Swagger/OpenAPI 类型定义
+ */
+/**
+ * Swagger 信息配置
+ */
+export interface SwaggerInfo {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+/**
+ * Swagger 配置
+ */
+export interface SwaggerOptions {
+    info: SwaggerInfo;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    basePath?: string;
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+/**
+ * API 操作元数据
+ */
+export interface ApiOperationMetadata {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    deprecated?: boolean;
+}
+/**
+ * API 参数元数据
+ */
+export interface ApiParamMetadata {
+    name: string;
+    description?: string;
+    required?: boolean;
+    schema?: {
+        type?: string;
+        format?: string;
+        enum?: unknown[];
+        default?: unknown;
+    };
+    in: 'query' | 'path' | 'header' | 'cookie';
+}
+/**
+ * API 请求体元数据
+ */
+export interface ApiBodyMetadata {
+    description?: string;
+    required?: boolean;
+    schema?: {
+        type?: string;
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    examples?: Record<string, unknown>;
+}
+/**
+ * API 响应元数据
+ */
+export interface ApiResponseMetadata {
+    status: number;
+    description?: string;
+    schema?: {
+        type?: string;
+        properties?: Record<string, unknown>;
+    };
+    examples?: Record<string, unknown>;
+}
+/**
+ * API 标签元数据
+ */
+export interface ApiTagMetadata {
+    name: string;
+    description?: string;
+}
+/**
+ * Swagger 路径项
+ */
+export interface SwaggerPathItem {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    parameters?: Array<{
+        name: string;
+        in: 'query' | 'path' | 'header' | 'cookie';
+        description?: string;
+        required?: boolean;
+        schema?: {
+            type?: string;
+            format?: string;
+            enum?: unknown[];
+            default?: unknown;
+        };
+    }>;
+    requestBody?: {
+        description?: string;
+        required?: boolean;
+        content?: {
+            'application/json'?: {
+                schema?: {
+                    type?: string;
+                    properties?: Record<string, unknown>;
+                    required?: string[];
+                };
+                examples?: Record<string, unknown>;
+            };
+        };
+    };
+    responses?: Record<string, {
+        description?: string;
+        content?: {
+            'application/json'?: {
+                schema?: {
+                    type?: string;
+                    properties?: Record<string, unknown>;
+                };
+                examples?: Record<string, unknown>;
+            };
+        };
+    }>;
+    deprecated?: boolean;
+}
+/**
+ * Swagger 文档结构
+ */
+export interface SwaggerDocument {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+        contact?: {
+            name?: string;
+            email?: string;
+            url?: string;
+        };
+        license?: {
+            name: string;
+            url?: string;
+        };
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    paths: Record<string, {
+        get?: SwaggerPathItem;
+        post?: SwaggerPathItem;
+        put?: SwaggerPathItem;
+        delete?: SwaggerPathItem;
+        patch?: SwaggerPathItem;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/swagger/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/swagger/types.ts"],"names":[],"mappings":"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"}

package/dist/swagger/ui.d.ts

@@ -0,0 +1,13 @@
+import type { Middleware } from '../middleware';
+import { SwaggerExtension } from './swagger-extension';
+/**
+ * 创建 Swagger UI 中间件
+ * @param extension - Swagger 扩展实例
+ * @param options - 配置选项
+ */
+export declare function createSwaggerUIMiddleware(extension: SwaggerExtension, options?: {
+    uiPath?: string;
+    jsonPath?: string;
+    title?: string;
+}): Middleware;
+//# sourceMappingURL=ui.d.ts.map

package/dist/swagger/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/swagger/ui.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAmDvD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,GACL,UAAU,CA+BZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/readme.md

@@ -31,7 +31,7 @@
   可扩展**：松耦合的模块系统、扩展系统与日志框架，既可以快速起步，也能按需裁剪。
 - **Monorepo 友好**：原生支持 Bun workspaces，使用 `workspace:*`
   协议管理内部依赖，配合 catalog 统一版本，完美适配多包协作场景。
-- **完整测试矩阵**：内置单元/集成测试、压力与基准测试用例，便于持续优化。
+- **完整测试矩阵**：内置单元/集成测试、压力与基准测试用例，Security 和 Swagger 模块测试覆盖完整，便于持续优化。
 
 ## 核心特性
 
@@ -43,6 +43,8 @@
   **中间件管道**：支持全局/控制器/方法级中间件，内置日志、错误处理、CORS、文件上传、静态资源等。
 - ✅ **输入校验**：声明式验证装饰器，直连 `ValidationError` 与异常过滤器。
 - 📡 **WebSocket**：`@WebSocketGateway`、`@OnMessage` 等装饰器级开发体验。
+- 📖 **Swagger/OpenAPI**：内置 Swagger 插件，支持 `@ApiTags`、`@ApiOperation`、`@ApiParam`、`@ApiBody`、`@ApiResponse` 等装饰器，自动生成 API 文档和 Swagger UI。
+- 🔐 **安全认证**：内置 SecurityModule，支持 JWT 和 OAuth2 认证，提供 `@Auth()` 装饰器进行角色权限控制。
 - 📚 **示例与文档**：多语言文档、基础/完整示例、基准脚本与最佳实践。
 
 ## 架构总览
@@ -126,11 +128,12 @@ bun --cwd=benchmark run bench:di     # 仅运行 DI 基准
 
 ## 示例与扩展
 
-- `examples/basic-app.ts`：最小可运行示例，覆盖 DI + Logger + Middleware。
-- `examples/full-app.ts`：包含验证、文件上传、WebSocket、复杂控制器。
-- `examples/multi-module-app.ts`：多模块示例，展示模块间的依赖关系和服务共享。
-- `packages/@dangao/bun-server/src/extensions/`：官方扩展（如
-  LoggerExtension），可用于注册第三方能力。
+- `examples/basic-app.ts`：最小可运行示例，覆盖 DI + Logger + Middleware + Swagger + ConfigModule。
+- `examples/full-app.ts`：包含验证、文件上传、WebSocket、复杂控制器，使用 ConfigModule 管理端口与中间件配置。
+- `examples/multi-module-app.ts`：多模块示例，展示模块间的依赖关系和服务共享，使用 ConfigModule 统一管理应用配置。
+- `examples/auth-app.ts`：完整的认证演示，包含 JWT + OAuth2 认证流程、前端演示页面，并通过 ConfigModule 管理应用标题和端口。
+- `packages/bun-server/src/extensions/`：官方扩展（如
+  LoggerExtension、SwaggerExtension），可用于注册第三方能力。
 
 ## 性能与 Benchmark
 
@@ -153,10 +156,11 @@ bun benchmark/di.bench.ts
 ## 文档与多语言支持
 
 - 中文默认文档位于 `docs/`
-  - `docs/api.md`
-  - `docs/guide.md`
-  - `docs/best-practices.md`
-  - `docs/migration.md`
+  - `docs/api.md` - API 参考文档
+  - `docs/guide.md` - 使用指南
+  - `docs/extensions.md` - 扩展系统说明（中间件、扩展、模块等）
+  - `docs/best-practices.md` - 最佳实践
+  - `docs/migration.md` - 迁移指南
 - 英文草稿位于
   `docs/en/`，与中文文件结构一致；如果缺失内容，请优先参考中文版本。