@dangao/bun-server 1.0.1 → 1.1.2

package/src/swagger/generator.ts

@@ -0,0 +1,234 @@
+import type { SwaggerDocument, SwaggerOptions, SwaggerPathItem } from './types';
+import { ControllerRegistry } from '../controller/controller';
+import { getControllerMetadata, getRouteMetadata } from '../controller/metadata';
+import {
+  getApiTags,
+  getApiOperation,
+  getApiParams,
+  getApiBody,
+  getApiResponses,
+} from './decorators';
+
+/**
+ * Swagger 文档生成器
+ */
+export class SwaggerGenerator {
+  private readonly options: SwaggerOptions;
+
+  public constructor(options: SwaggerOptions) {
+    this.options = options;
+  }
+
+  /**
+   * 生成 Swagger 文档
+   */
+  public generate(): SwaggerDocument {
+    const document: SwaggerDocument = {
+      openapi: '3.0.0',
+      info: {
+        title: this.options.info.title,
+        version: this.options.info.version,
+        description: this.options.info.description,
+        contact: this.options.info.contact,
+        license: this.options.info.license,
+      },
+      servers: this.options.servers,
+      tags: this.options.tags,
+      paths: {},
+    };
+
+    // 从 ControllerRegistry 获取所有控制器
+    const controllerRegistry = ControllerRegistry.getInstance();
+    const controllers = controllerRegistry.getRegisteredControllers();
+
+    if (controllers.length === 0) {
+      return document;
+    }
+
+    for (const controllerClass of controllers) {
+      const controllerMetadata = getControllerMetadata(controllerClass);
+      if (!controllerMetadata) {
+        console.log(`[SwaggerGenerator] No metadata for controller: ${controllerClass.name}`);
+        continue;
+      }
+
+      const basePath = controllerMetadata.path;
+      const prototype = controllerClass.prototype;
+      
+      // 获取路由元数据 - 从原型获取
+      const routes = getRouteMetadata(prototype);
+
+      // 如果没有路由，跳过这个控制器
+      if (!routes || routes.length === 0) {
+        continue;
+      }
+
+      // 获取控制器级别的标签
+      const controllerTags = getApiTags(controllerClass);
+
+      for (const route of routes) {
+        // 如果没有 propertyKey，尝试从 handler 函数名或原型中查找
+        let propertyKey = route.propertyKey;
+        if (!propertyKey && route.handler) {
+          // 尝试从 handler 函数名获取
+          propertyKey = route.handler.name;
+          // 如果还是没有，从原型中查找
+          if (!propertyKey || propertyKey === '') {
+            const propertyNames = Object.getOwnPropertyNames(prototype);
+            for (const key of propertyNames) {
+              if (key === 'constructor') continue;
+              const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+              if (descriptor && descriptor.value === route.handler) {
+                propertyKey = key;
+                break;
+              }
+            }
+          }
+        }
+        
+        if (!propertyKey) {
+          continue;
+        }
+
+        const method = route.method.toLowerCase() as 'get' | 'post' | 'put' | 'delete' | 'patch';
+        // 组合基础路径和方法路径
+        let methodPath = route.path;
+        // 如果方法路径不是以 / 开头，需要添加
+        if (methodPath && !methodPath.startsWith('/')) {
+          methodPath = '/' + methodPath;
+        }
+        // 将路径参数格式从 :param 转换为 {param}（OpenAPI 格式）
+        const swaggerPath = (basePath + methodPath).replace(/:([^/]+)/g, '{$1}');
+        const fullPath = this.normalizePath(swaggerPath);
+
+        // 获取方法级别的元数据
+        const operationMetadata = getApiOperation(prototype, propertyKey);
+        const methodTags = getApiTags(prototype, propertyKey);
+        const params = getApiParams(prototype, propertyKey);
+        const body = getApiBody(prototype, propertyKey);
+        const responses = getApiResponses(prototype, propertyKey);
+
+        // 合并标签
+        const tags = [...new Set([...controllerTags, ...methodTags])];
+
+        const pathItem: SwaggerPathItem = {
+          summary: operationMetadata?.summary,
+          description: operationMetadata?.description,
+          operationId: operationMetadata?.operationId || propertyKey,
+          tags: tags.length > 0 ? tags : undefined,
+          deprecated: operationMetadata?.deprecated,
+        };
+
+        // 处理参数
+        const pathParams: Array<{
+          name: string;
+          in: 'query' | 'path' | 'header' | 'cookie';
+          description?: string;
+          required?: boolean;
+          schema?: {
+            type?: string;
+            format?: string;
+            enum?: unknown[];
+            default?: unknown;
+          };
+        }> = [];
+
+        // 自动从路径中提取路径参数
+        const pathParamMatches = fullPath.matchAll(/\{([^}]+)\}/g);
+        for (const match of pathParamMatches) {
+          const paramName = match[1];
+          // 检查是否已经有手动定义的参数
+          const existingParam = params.find((p) => p.metadata.name === paramName && p.metadata.in === 'path');
+          if (!existingParam) {
+            // 自动添加路径参数
+            pathParams.push({
+              name: paramName,
+              in: 'path',
+              required: true,
+              schema: { type: 'string' },
+            });
+          }
+        }
+
+        // 添加手动定义的参数
+        for (const param of params) {
+          pathParams.push({
+            name: param.metadata.name,
+            in: param.metadata.in,
+            description: param.metadata.description,
+            required: param.metadata.required,
+            schema: param.metadata.schema,
+          });
+        }
+
+        if (pathParams.length > 0) {
+          pathItem.parameters = pathParams;
+        }
+
+        // 处理请求体
+        if (body) {
+          pathItem.requestBody = {
+            description: body.description,
+            required: body.required,
+            content: {
+              'application/json': {
+                schema: body.schema,
+                examples: body.examples,
+              },
+            },
+          };
+        }
+
+        // 处理响应
+        if (responses.length > 0) {
+          pathItem.responses = {};
+          for (const response of responses) {
+            pathItem.responses[String(response.status)] = {
+              description: response.description,
+              content: {
+                'application/json': {
+                  schema: response.schema,
+                  examples: response.examples,
+                },
+              },
+            };
+          }
+        } else {
+          // 默认响应
+          pathItem.responses = {
+            '200': {
+              description: 'Success',
+            },
+          };
+        }
+
+        // 初始化路径对象
+        if (!document.paths[fullPath]) {
+          document.paths[fullPath] = {};
+        }
+
+        document.paths[fullPath][method] = pathItem;
+      }
+    }
+
+    return document;
+  }
+
+  /**
+   * 规范化路径
+   */
+  private normalizePath(path: string): string {
+    // 移除重复的斜杠
+    path = path.replace(/\/+/g, '/');
+    // 确保以 / 开头
+    if (!path.startsWith('/')) {
+      path = '/' + path;
+    }
+    // 移除末尾的斜杠（除非是根路径）
+    if (path.length > 1 && path.endsWith('/')) {
+      path = path.slice(0, -1);
+    }
+    return path;
+  }
+}
+

package/src/swagger/index.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './decorators';
+export * from './generator';
+export * from './swagger-extension';
+export * from './swagger-module';
+export * from './ui';
+

package/src/swagger/swagger-extension.ts

@@ -0,0 +1,41 @@
+import type { Container } from '../di/container';
+import type { ApplicationExtension } from '../extensions/types';
+import { SwaggerGenerator } from './generator';
+import type { SwaggerOptions } from './types';
+
+/**
+ * Swagger 扩展
+ */
+export class SwaggerExtension implements ApplicationExtension {
+  private readonly options: SwaggerOptions;
+  private generator?: SwaggerGenerator;
+
+  public constructor(options: SwaggerOptions) {
+    this.options = options;
+  }
+
+  /**
+   * 注册扩展
+   */
+  public register(_container: Container): void {
+    this.generator = new SwaggerGenerator(this.options);
+  }
+
+  /**
+   * 获取 Swagger 文档生成器
+   */
+  public getGenerator(): SwaggerGenerator {
+    if (!this.generator) {
+      this.generator = new SwaggerGenerator(this.options);
+    }
+    return this.generator;
+  }
+
+  /**
+   * 生成 Swagger JSON
+   */
+  public generateJSON(): string {
+    return JSON.stringify(this.getGenerator().generate(), null, 2);
+  }
+}
+

package/src/swagger/swagger-module.ts

@@ -0,0 +1,83 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import { SwaggerExtension } from './swagger-extension';
+import { createSwaggerUIMiddleware } from './ui';
+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
+ */
+@Module({
+  extensions: [
+    // 将在运行时根据配置创建
+  ],
+  middlewares: [
+    // 将在运行时根据配置创建
+  ],
+})
+export class SwaggerModule {
+  /**
+   * 创建 Swagger 模块
+   * @param options - 模块配置
+   */
+  public static forRoot(options: SwaggerModuleOptions): typeof SwaggerModule {
+    const extensions: any[] = [];
+    const middlewares: any[] = [];
+
+    // 创建 Swagger 扩展
+    const swaggerExtension = new SwaggerExtension({
+      info: options.info,
+      servers: options.servers,
+      basePath: options.basePath,
+      tags: options.tags,
+    });
+    extensions.push(swaggerExtension);
+
+    // 如果启用 UI，添加中间件
+    if (options.enableUI !== false) {
+      const uiMiddleware = createSwaggerUIMiddleware(swaggerExtension, {
+        uiPath: options.uiPath || '/swagger',
+        jsonPath: options.jsonPath || '/swagger.json',
+        title: options.uiTitle || options.info.title || 'API Documentation',
+      });
+      middlewares.push(uiMiddleware);
+    }
+
+    // 动态更新模块元数据
+    const existingMetadata = Reflect.getMetadata(MODULE_METADATA_KEY, SwaggerModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      extensions,
+      middlewares,
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, SwaggerModule);
+
+    return SwaggerModule;
+  }
+}
+

package/src/swagger/types.ts

@@ -0,0 +1,188 @@
+/**
+ * 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;
+  }>;
+}
+

package/src/swagger/ui.ts

@@ -0,0 +1,98 @@
+import type { Context } from '../core/context';
+import type { Middleware, NextFunction } from '../middleware';
+import { SwaggerExtension } from './swagger-extension';
+
+/**
+ * Swagger UI HTML 模板
+ */
+const SWAGGER_UI_HTML = (jsonUrl: string, title: string) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title} - Swagger UI</title>
+  <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css" />
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *, *:before, *:after {
+      box-sizing: inherit;
+    }
+    body {
+      margin:0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js"></script>
+  <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-standalone-preset.js"></script>
+  <script>
+    window.onload = function() {
+      const ui = SwaggerUIBundle({
+        url: "${jsonUrl}",
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      });
+    };
+  </script>
+</body>
+</html>`;
+
+/**
+ * 创建 Swagger UI 中间件
+ * @param extension - Swagger 扩展实例
+ * @param options - 配置选项
+ */
+export function createSwaggerUIMiddleware(
+  extension: SwaggerExtension,
+  options: {
+    uiPath?: string;
+    jsonPath?: string;
+    title?: string;
+  } = {},
+): Middleware {
+  const uiPath = options.uiPath || '/swagger';
+  const jsonPath = options.jsonPath || '/swagger.json';
+  const title = options.title || 'API Documentation';
+
+  return async (ctx: Context, next: NextFunction): Promise<Response> => {
+    const url = new URL(ctx.request.url);
+    const pathname = url.pathname;
+
+    // Swagger UI 页面
+    if (pathname === uiPath || pathname === `${uiPath}/`) {
+      const html = SWAGGER_UI_HTML(jsonPath, title);
+      return new Response(html, {
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+        },
+      });
+    }
+
+    // Swagger JSON
+    if (pathname === jsonPath) {
+      const json = extension.generateJSON();
+      return new Response(json, {
+        headers: {
+          'Content-Type': 'application/json; charset=utf-8',
+        },
+      });
+    }
+
+    return await next();
+  };
+}
+