@hazeljs/swagger 0.8.6 → 0.8.7

package/dist/swagger.service.d.ts

@@ -1,36 +1,23 @@
-import { SwaggerOperation, SwaggerSchema } from './swagger.types';
+import type { SwaggerBuildOptions, SwaggerSpec } from './swagger.types';
 import { Type } from '@hazeljs/core';
-export interface AutoSwaggerOptions {
-    title?: string;
-    description?: string;
-    version?: string;
-    autoGenerateOperations?: boolean;
-}
-export interface SwaggerSpec {
-    openapi: string;
-    info: {
-        title?: string;
-        description?: string;
-        version?: string;
-    };
-    paths: Record<string, Record<string, SwaggerOperation>>;
-    components: {
-        schemas: Record<string, SwaggerSchema>;
-    };
-    tags?: Array<{
-        name: string;
-        description: string;
-    }>;
-}
 export declare class SwaggerService {
     private spec;
-    generateAutoSpec(moduleType: Type<unknown>, options?: AutoSwaggerOptions): SwaggerSpec;
-    private processControllerAuto;
-    private processRouteAuto;
+    /** Build spec by walking the module tree (imports + controllers). */
+    generateAutoSpec(moduleType: Type<unknown>, options?: SwaggerBuildOptions): SwaggerSpec;
+    /**
+     * Build spec from an explicit controller list.
+     * Controllers do not require `@Swagger` on the class; routes without `@ApiOperation`
+     * are filled when `autoGenerateOperations` is true (default).
+     */
+    generateSpec(controllers: Type<unknown>[], options?: SwaggerBuildOptions): SwaggerSpec;
+    private buildOpenApiFromControllers;
+    private normalizePrefix;
+    private joinPathSegments;
+    private processControllerRoutes;
+    private processRoute;
     private generateAutoOperation;
     private extractPathParameters;
     private addDefaultSchemas;
-    generateSpec(controllers: Type<unknown>[]): SwaggerSpec;
     private normalizePath;
 }
 //# sourceMappingURL=swagger.service.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"swagger.service.d.ts","sourceRoot":"","sources":["../src/swagger.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAGrC,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;IACxD,UAAU,EAAE;QACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;KACxC,CAAC;IACF,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAQD,qBACa,cAAc;IACzB,OAAO,CAAC,IAAI,CAOV;IAGF,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW;IAqCtF,OAAO,CAAC,qBAAqB;IA8B7B,OAAO,CAAC,gBAAgB;IA8BxB,OAAO,CAAC,qBAAqB;IAkG7B,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,iBAAiB;IAyCzB,YAAY,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,WAAW;IAsGvD,OAAO,CAAC,aAAa;CAStB"}
+{"version":3,"file":"swagger.service.d.ts","sourceRoot":"","sources":["../src/swagger.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EAGnB,WAAW,EACZ,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AASrC,qBACa,cAAc;IACzB,OAAO,CAAC,IAAI,CAOV;IAEF,qEAAqE;IACrE,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,WAAW;IAWvF;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,WAAW;IAoBtF,OAAO,CAAC,2BAA2B;IAgFnC,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,uBAAuB;IA2B/B,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,qBAAqB;IA+F7B,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,iBAAiB;IAwCzB,OAAO,CAAC,aAAa;CAOtB"}

package/dist/swagger.service.js

@@ -25,76 +25,144 @@ let SwaggerService = class SwaggerService {
             },
         };
     }
-    // Auto-generate spec from module without explicit Swagger decorators
+    /** Build spec by walking the module tree (imports + controllers). */
     generateAutoSpec(moduleType, options) {
         try {
             core_2.default.debug('Auto-generating Swagger spec from module:', moduleType.name);
-            // Reset spec
-            this.spec = {
-                openapi: '3.0.0',
-                info: {
-                    title: options?.title || 'HazelJS API',
-                    description: options?.description || 'Auto-generated API documentation',
-                    version: options?.version || '1.0.0',
-                },
-                paths: {},
-                components: {
-                    schemas: {},
-                },
-                tags: [],
-            };
             const controllers = (0, core_3.collectControllersFromModule)(moduleType);
-            // Process each controller
-            controllers.forEach((controller) => {
-                this.processControllerAuto(controller, options?.autoGenerateOperations !== false);
-            });
-            // Add default error schemas
-            this.addDefaultSchemas();
-            core_2.default.debug('Auto-generated Swagger specification completed');
-            return this.spec;
+            return this.buildOpenApiFromControllers(controllers, options);
         }
         catch (error) {
             core_2.default.error('Failed to auto-generate Swagger specification:', error);
             throw error;
         }
     }
-    processControllerAuto(controller, autoGenerateOps) {
-        if (!controller)
-            return;
-        // Get controller path from metadata
+    /**
+     * Build spec from an explicit controller list.
+     * Controllers do not require `@Swagger` on the class; routes without `@ApiOperation`
+     * are filled when `autoGenerateOperations` is true (default).
+     */
+    generateSpec(controllers, options) {
+        try {
+            if (!Array.isArray(controllers)) {
+                throw new Error('Controllers must be an array');
+            }
+            core_2.default.debug('Generating spec for controllers:', controllers.map((c) => c?.name || 'undefined'));
+            return this.buildOpenApiFromControllers(controllers, options);
+        }
+        catch (error) {
+            if (process.env.NODE_ENV !== 'test') {
+                core_2.default.error('Failed to generate Swagger specification:', error);
+            }
+            throw error;
+        }
+    }
+    buildOpenApiFromControllers(controllers, options = {}) {
+        const autoGenerateOps = options.autoGenerateOperations !== false;
+        this.spec = {
+            openapi: '3.0.0',
+            info: {},
+            paths: {},
+            components: {
+                schemas: {},
+            },
+        };
+        if (options.title !== undefined) {
+            this.spec.info.title = options.title;
+        }
+        if (options.description !== undefined) {
+            this.spec.info.description = options.description;
+        }
+        if (options.version !== undefined) {
+            this.spec.info.version = options.version;
+        }
+        if (options.servers?.length) {
+            this.spec.servers = options.servers;
+        }
+        if (options.securitySchemes && Object.keys(options.securitySchemes).length > 0) {
+            this.spec.components.securitySchemes = { ...options.securitySchemes };
+        }
+        if (options.security?.length) {
+            this.spec.security = options.security;
+        }
+        this.addDefaultSchemas();
+        const pathPrefix = this.normalizePrefix(options.globalPrefix);
+        for (const controller of controllers) {
+            if (!controller || typeof controller !== 'function') {
+                if (process.env.NODE_ENV !== 'test') {
+                    core_2.default.warn('Invalid controller found:', controller);
+                }
+                continue;
+            }
+            const swaggerOptions = (0, swagger_decorator_1.getSwaggerMetadata)(controller.prototype);
+            if (swaggerOptions) {
+                if (!this.spec.info.title) {
+                    this.spec.info = {
+                        title: swaggerOptions.title,
+                        description: swaggerOptions.description,
+                        version: swaggerOptions.version,
+                    };
+                }
+                if (swaggerOptions.tags && !this.spec.tags?.length) {
+                    this.spec.tags = swaggerOptions.tags;
+                }
+            }
+            this.processControllerRoutes(controller, pathPrefix, autoGenerateOps);
+        }
+        if (!this.spec.info.title) {
+            this.spec.info.title = 'HazelJS API';
+        }
+        if (!this.spec.info.description) {
+            this.spec.info.description = 'API documentation';
+        }
+        if (!this.spec.info.version) {
+            this.spec.info.version = '1.0.0';
+        }
+        core_2.default.debug('Generated Swagger specification:', this.spec);
+        return this.spec;
+    }
+    normalizePrefix(prefix) {
+        if (!prefix)
+            return '';
+        let p = prefix.startsWith('/') ? prefix : `/${prefix}`;
+        p = p.replace(/\/$/, '');
+        return p;
+    }
+    joinPathSegments(...segments) {
+        const parts = [];
+        for (const seg of segments) {
+            if (!seg)
+                continue;
+            for (const piece of String(seg).split('/')) {
+                if (piece)
+                    parts.push(piece);
+            }
+        }
+        return parts.length ? `/${parts.join('/')}` : '';
+    }
+    processControllerRoutes(controller, pathPrefix, autoGenerateOps) {
         const controllerMetadata = Reflect.getMetadata('hazel:controller', controller) || {};
         const basePath = controllerMetadata.path || '';
-        // Get API tags from metadata
         const apiTags = Reflect.getMetadata('hazel:api:tags', controller) || [];
-        // Add controller as a tag if not already present
-        if (!this.spec.tags)
-            this.spec.tags = [];
         const controllerTag = {
             name: apiTags.length > 0 ? apiTags[0] : controller.name,
             description: `${controller.name} endpoints`,
         };
-        if (!this.spec.tags.find((tag) => tag.name === controllerTag.name)) {
-            this.spec.tags.push(controllerTag);
-        }
-        // Get route metadata
         const routes = Reflect.getMetadata('hazel:routes', controller) || [];
-        // Process each route
-        routes.forEach((route) => {
-            this.processRouteAuto(controller, route, basePath, controllerTag.name, autoGenerateOps);
-        });
+        for (const route of routes) {
+            this.processRoute(controller, route, basePath, pathPrefix, controllerTag.name, autoGenerateOps);
+        }
     }
-    processRouteAuto(controller, route, basePath, tag, autoGenerateOps) {
+    processRoute(controller, route, basePath, pathPrefix, tag, autoGenerateOps) {
         const { path, method, propertyKey } = route;
-        const fullPath = this.normalizePath(`${basePath}${path}`);
-        // Check for existing operation metadata
+        const fullPath = this.normalizePath(this.joinPathSegments(pathPrefix, basePath, path));
+        const pathForParams = this.joinPathSegments(basePath, path);
         let operation = (0, swagger_decorator_1.getOperationMetadata)(controller.prototype, propertyKey);
-        // Auto-generate operation if not found and auto-generation is enabled
         if (!operation && autoGenerateOps) {
-            operation = this.generateAutoOperation(method, propertyKey, tag, route);
+            operation = this.generateAutoOperation(method, propertyKey, tag, pathForParams);
         }
         if (!operation)
             return;
-        // Add operation to paths
         const pathItem = this.spec.paths[fullPath] || {};
         pathItem[method.toLowerCase()] = {
             ...operation,
@@ -102,18 +170,19 @@ let SwaggerService = class SwaggerService {
         };
         this.spec.paths[fullPath] = pathItem;
     }
-    generateAutoOperation(method, propertyKey, tag, route) {
+    generateAutoOperation(method, propertyKey, tag, pathForParams) {
         const methodName = String(propertyKey);
-        const isGetMethod = method.toLowerCase() === 'get';
-        const isPostMethod = method.toLowerCase() === 'post';
-        const isPutMethod = method.toLowerCase() === 'put';
-        const isDeleteMethod = method.toLowerCase() === 'delete';
-        // Generate summary based on method name
+        const m = method.toLowerCase();
+        const isGetMethod = m === 'get';
+        const isPostMethod = m === 'post';
+        const isPutMethod = m === 'put';
+        const isPatchMethod = m === 'patch';
+        const isDeleteMethod = m === 'delete';
         let summary = '';
         if (methodName.includes('create') || isPostMethod) {
             summary = `Create new resource`;
         }
-        else if (methodName.includes('update') || isPutMethod) {
+        else if (methodName.includes('update') || isPutMethod || isPatchMethod) {
             summary = `Update resource`;
         }
         else if (methodName.includes('delete') || isDeleteMethod) {
@@ -125,6 +194,7 @@ let SwaggerService = class SwaggerService {
         else {
             summary = `${method.toUpperCase()} ${methodName}`;
         }
+        const errorSchema = { $ref: '#/components/schemas/Error' };
         const operation = {
             summary,
             description: `Auto-generated ${method.toUpperCase()} operation`,
@@ -145,10 +215,25 @@ let SwaggerService = class SwaggerService {
                         },
                     },
                 },
+                '400': {
+                    description: 'Bad request',
+                    content: {
+                        'application/json': {
+                            schema: errorSchema,
+                        },
+                    },
+                },
+                '500': {
+                    description: 'Internal server error',
+                    content: {
+                        'application/json': {
+                            schema: errorSchema,
+                        },
+                    },
+                },
             },
         };
-        // Add parameters for path variables - need to extract from the route path
-        const pathParams = this.extractPathParameters(route.path);
+        const pathParams = this.extractPathParameters(pathForParams);
         if (pathParams.length > 0) {
             operation.parameters = pathParams.map((param) => ({
                 name: param,
@@ -157,8 +242,7 @@ let SwaggerService = class SwaggerService {
                 schema: { type: 'string' },
             }));
         }
-        // Add request body for POST/PUT/PATCH
-        if (isPostMethod || isPutMethod) {
+        if (isPostMethod || isPutMethod || isPatchMethod) {
             operation.requestBody = {
                 required: true,
                 content: {
@@ -170,38 +254,18 @@ let SwaggerService = class SwaggerService {
                 },
             };
         }
-        // Add common error responses
-        if (operation.responses) {
-            operation.responses['400'] = {
-                description: 'Bad request',
-                content: {
-                    'application/json': {
-                        schema: { type: 'object' },
-                    },
-                },
-            };
-            operation.responses['500'] = {
-                description: 'Internal server error',
-                content: {
-                    'application/json': {
-                        schema: { type: 'object' },
-                    },
-                },
-            };
-        }
         return operation;
     }
-    extractPathParameters(path) {
+    extractPathParameters(routePath) {
         const params = [];
         const paramRegex = /:([^/]+)/g;
         let match;
-        while ((match = paramRegex.exec(path)) !== null) {
+        while ((match = paramRegex.exec(routePath)) !== null) {
             params.push(match[1]);
         }
         return params;
     }
     addDefaultSchemas() {
-        // Add common error schemas
         this.spec.components.schemas.Error = {
             type: 'object',
             properties: {
@@ -239,95 +303,12 @@ let SwaggerService = class SwaggerService {
             },
         };
     }
-    generateSpec(controllers) {
-        try {
-            if (!Array.isArray(controllers)) {
-                throw new Error('Controllers must be an array');
-            }
-            core_2.default.debug('Generating spec for controllers:', controllers.map((c) => c?.name || 'undefined'));
-            // Reset spec
-            this.spec = {
-                openapi: '3.0.0',
-                info: {},
-                paths: {},
-                components: {
-                    schemas: {},
-                },
-            };
-            // Process each controller
-            controllers.forEach((controller) => {
-                if (!controller || typeof controller !== 'function') {
-                    if (process.env.NODE_ENV !== 'test') {
-                        core_2.default.warn('Invalid controller found:', controller);
-                    }
-                    return;
-                }
-                // Get Swagger metadata from the controller prototype
-                const swaggerOptions = (0, swagger_decorator_1.getSwaggerMetadata)(controller.prototype);
-                if (!swaggerOptions) {
-                    core_2.default.debug(`No Swagger metadata found for controller: ${controller.name}`);
-                    return;
-                }
-                core_2.default.debug(`Processing controller: ${controller.name}`, swaggerOptions);
-                // Update info if not already set
-                if (!this.spec.info.title) {
-                    this.spec.info = {
-                        title: swaggerOptions.title,
-                        description: swaggerOptions.description,
-                        version: swaggerOptions.version,
-                    };
-                }
-                // Add tags if not already set
-                if (swaggerOptions.tags && !this.spec.tags) {
-                    this.spec.tags = swaggerOptions.tags;
-                }
-                // Get controller path from metadata
-                const controllerMetadata = Reflect.getMetadata('hazel:controller', controller) || {};
-                const basePath = controllerMetadata.path || '';
-                // Get route metadata
-                const routes = Reflect.getMetadata('hazel:routes', controller);
-                if (!routes) {
-                    core_2.default.debug(`No routes found for controller: ${controller.name}`);
-                    return;
-                }
-                core_2.default.debug(`Found routes for ${controller.name}:`, routes);
-                // Process each route
-                routes.forEach((route) => {
-                    const { path, method, propertyKey } = route;
-                    const fullPath = this.normalizePath(`${basePath}${path}`);
-                    const operation = (0, swagger_decorator_1.getOperationMetadata)(controller.prototype, propertyKey);
-                    if (!operation) {
-                        core_2.default.debug(`No operation metadata found for method: ${String(propertyKey)}`);
-                        return;
-                    }
-                    core_2.default.debug(`Adding operation for ${method} ${fullPath}`);
-                    // Add operation to paths
-                    const pathItem = this.spec.paths[fullPath] || {};
-                    pathItem[method.toLowerCase()] = {
-                        ...operation,
-                        tags: operation.tags || [controller.name],
-                    };
-                    this.spec.paths[fullPath] = pathItem;
-                });
-            });
-            core_2.default.debug('Generated Swagger specification:', this.spec);
-            return this.spec;
-        }
-        catch (error) {
-            if (process.env.NODE_ENV !== 'test') {
-                core_2.default.error('Failed to generate Swagger specification:', error);
-            }
-            throw error;
-        }
-    }
     normalizePath(path) {
-        // Remove trailing slash
         let normalized = path.replace(/\/$/, '');
-        // Ensure path starts with slash
         if (!normalized.startsWith('/')) {
             normalized = '/' + normalized;
         }
-        return normalized;
+        return normalized || '/';
     }
 };
 exports.SwaggerService = SwaggerService;