@buenojs/bueno 0.8.10 → 0.8.11

package/dist/openapi/route-scanner.js

@@ -0,0 +1,174 @@
+/**
+ * Route Scanner
+ *
+ * Scans controllers and extracts OpenAPI operation metadata from decorators.
+ * Combines HTTP method decorators, parameter documentation, and responses
+ * into OpenAPI operation objects.
+ */
+import { getApiMetadata, getApiMethodMetadata } from './metadata';
+// Read controller path and route list from the modules metadata stores
+import { getMetadata, getPrototypeMetadata } from '../modules/metadata';
+/**
+ * RouteScanner - Scans controllers and extracts OpenAPI operations
+ */
+export class RouteScanner {
+    schemaGenerator;
+    constructor(schemaGenerator) {
+        this.schemaGenerator = schemaGenerator;
+    }
+    /**
+     * Scan all controllers and generate OpenAPI paths
+     */
+    scanControllers(controllers) {
+        const paths = {};
+        for (const controller of controllers) {
+            // Skip controllers marked with @ApiExcludeController
+            if (getApiMetadata(controller, 'api:exclude')) {
+                continue;
+            }
+            // Get controller base path from @Controller decorator (stored in modules metadata)
+            const basePath = getMetadata(controller, 'path') ?? '';
+            // Get routes from prototype metadata (stored by @Get, @Post, etc. in modules metadata)
+            const routes = getPrototypeMetadata(controller.prototype, 'routes') ?? [];
+            // Get class-level tags and security from OpenAPI metadata
+            const classLevelTags = getApiMetadata(controller, 'api:tags') ?? [];
+            const classLevelSecurity = getApiMetadata(controller, 'api:security') ?? [];
+            // Process each route in the controller
+            for (const route of routes) {
+                const prototype = controller.prototype;
+                const handlerKey = route.handler;
+                // Skip endpoints marked with @ApiExcludeEndpoint (per-method metadata)
+                if (getApiMethodMetadata(prototype, `api:exclude:${String(handlerKey)}`)) {
+                    continue;
+                }
+                const fullPath = this.convertPathToOpenAPI(basePath + route.path);
+                // Ensure path exists in paths object
+                if (!paths[fullPath]) {
+                    paths[fullPath] = {};
+                }
+                // Generate the operation
+                const operation = this.generateOperation(controller, route, classLevelTags, classLevelSecurity, basePath);
+                // Add operation to the path (always write — overwrite if duplicate method)
+                paths[fullPath][route.method.toLowerCase()] = operation;
+            }
+        }
+        return paths;
+    }
+    /**
+     * Generate an OpenAPI operation for a single route
+     */
+    generateOperation(controller, route, classLevelTags, classLevelSecurity, basePath) {
+        const prototype = controller.prototype;
+        const handlerKey = String(route.handler);
+        // Helper to read per-method OpenAPI metadata — stored under "api:<key>:<handler>"
+        const getMethodMeta = (key) => getApiMethodMetadata(prototype, `${key}:${handlerKey}`);
+        // Get operation metadata from decorators
+        const operationMeta = getMethodMeta('api:operation');
+        const responseMeta = getMethodMeta('api:responses') ?? [];
+        const paramMeta = getMethodMeta('api:params') ?? [];
+        const queryMeta = getMethodMeta('api:query') ?? [];
+        const headerMeta = getMethodMeta('api:headers') ?? [];
+        const bodyMeta = getMethodMeta('api:body');
+        const methodLevelTags = getMethodMeta('api:tags') ?? [];
+        const methodLevelSecurity = getMethodMeta('api:security') ?? [];
+        // Build parameters array
+        const parameters = [
+            ...paramMeta.map((p) => ({
+                name: p.name,
+                in: 'path',
+                description: p.description,
+                required: p.required ?? true,
+                example: p.example,
+                schema: p.schema,
+            })),
+            ...queryMeta.map((q) => ({
+                name: q.name,
+                in: 'query',
+                description: q.description,
+                required: q.required ?? false,
+                example: q.example,
+                schema: q.schema,
+            })),
+            ...headerMeta.map((h) => ({
+                name: h.name,
+                in: 'header',
+                description: h.description,
+                required: h.required,
+                schema: h.schema,
+            })),
+        ];
+        // Build responses object (properly typed)
+        const responses = {};
+        for (const resp of responseMeta) {
+            const statusCode = String(resp.status);
+            const response = { description: resp.description };
+            // Add schema if provided
+            if (resp.type || resp.schema) {
+                let schema = resp.schema ?? {};
+                if (resp.type) {
+                    if (Array.isArray(resp.type)) {
+                        const itemSchema = this.schemaGenerator.generateSchema(resp.type[0]);
+                        schema = { type: 'array', items: itemSchema };
+                    }
+                    else {
+                        schema = this.schemaGenerator.generateSchema(resp.type);
+                    }
+                }
+                const mediaType = { schema };
+                response.content = { 'application/json': mediaType };
+            }
+            responses[statusCode] = response;
+        }
+        // If no responses documented, add a default 200
+        if (Object.keys(responses).length === 0) {
+            responses['200'] = { description: 'Success' };
+        }
+        // Build request body if present
+        const requestBody = bodyMeta
+            ? {
+                description: bodyMeta.description,
+                required: bodyMeta.required ?? true,
+                content: {
+                    'application/json': {
+                        schema: bodyMeta.schema ??
+                            (bodyMeta.type
+                                ? this.schemaGenerator.generateSchema(bodyMeta.type)
+                                : { type: 'object' }),
+                    },
+                },
+            }
+            : undefined;
+        // Combine tags (class-level + method-level, deduplicated)
+        const tags = [...new Set([...classLevelTags, ...methodLevelTags])];
+        // Combine security
+        const security = [...classLevelSecurity, ...methodLevelSecurity];
+        // Build the operation
+        const operation = {
+            operationId: operationMeta?.operationId ??
+                `${route.method.toLowerCase()}_${basePath.replace(/\//g, '_')}_${handlerKey}`,
+            summary: operationMeta?.summary,
+            description: operationMeta?.description,
+            tags: tags.length > 0 ? tags : undefined,
+            parameters: parameters.length > 0 ? parameters : undefined,
+            requestBody,
+            responses,
+            deprecated: operationMeta?.deprecated,
+            security: security.length > 0 ? security : undefined,
+        };
+        return operation;
+    }
+    /**
+     * Convert a route pattern from :param format to {param} format (OpenAPI style)
+     * Handles optional params (:param?) and regex params (:param<regex>)
+     */
+    convertPathToOpenAPI(pattern) {
+        return pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)\??(?:<[^>]+>)?/g, '{$1}');
+    }
+    /**
+     * Get the schema generator instance
+     */
+    getSchemaGenerator() {
+        return this.schemaGenerator;
+    }
+}
+//# sourceMappingURL=route-scanner.js.map

package/dist/openapi/route-scanner.js.map

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

package/dist/openapi/schema-generator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Schema Generator
+ *
+ * Converts TypeScript class types and @ApiProperty decorators into OpenAPI schemas.
+ */
+import type { Constructor, OpenAPISchema } from './types';
+/**
+ * SchemaGenerator - Converts TypeScript types to OpenAPI schemas
+ */
+export declare class SchemaGenerator {
+    private schemas;
+    private typeNames;
+    private typeCounter;
+    /**
+     * Generate an OpenAPI schema from a TypeScript type
+     * Supports classes, interfaces (via decorators), primitives, arrays
+     */
+    generateSchema(type: Constructor | string | Function): OpenAPISchema;
+    /**
+     * Generate schema for an object/class type
+     * Reads @ApiProperty metadata from class properties
+     */
+    private generateObjectSchema;
+    /**
+     * Generate schema from an @ApiProperty options object
+     */
+    private generatePropertySchema;
+    /**
+     * Generate schema for a primitive TypeScript type
+     */
+    private generatePrimitiveSchema;
+    /**
+     * Map string type names to OpenAPI schema
+     */
+    private mapStringType;
+    /**
+     * Check if type is a built-in TypeScript type
+     */
+    private isBuiltInType;
+    /**
+     * Get the name for a type (for referencing in components.schemas)
+     */
+    private getTypeName;
+    /**
+     * Get all generated schemas (for components.schemas)
+     */
+    getSchemas(): Record<string, OpenAPISchema>;
+    /**
+     * Clear cached schemas
+     */
+    clear(): void;
+}
+//# sourceMappingURL=schema-generator.d.ts.map

package/dist/openapi/schema-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-generator.d.ts","sourceRoot":"","sources":["../../src/openapi/schema-generator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAsB,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG9E;;GAEG;AACH,qBAAa,eAAe;IAC3B,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,WAAW,CAAK;IAExB;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa;IAiCpE;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAsC5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkD9B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAe/B;;OAEG;IACH,OAAO,CAAC,aAAa;IA+BrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,WAAW;IAkBnB;;OAEG;IACH,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAQ3C;;OAEG;IACH,KAAK,IAAI,IAAI;CAKb"}

package/dist/openapi/schema-generator.js

@@ -0,0 +1,236 @@
+/**
+ * Schema Generator
+ *
+ * Converts TypeScript class types and @ApiProperty decorators into OpenAPI schemas.
+ */
+import { getApiPropertyMetadata, getApiPropertyKeys } from './metadata';
+/**
+ * SchemaGenerator - Converts TypeScript types to OpenAPI schemas
+ */
+export class SchemaGenerator {
+    schemas = new Map();
+    typeNames = new Map();
+    typeCounter = 0;
+    /**
+     * Generate an OpenAPI schema from a TypeScript type
+     * Supports classes, interfaces (via decorators), primitives, arrays
+     */
+    generateSchema(type) {
+        // Handle string type names (primitives like 'string', 'number')
+        if (typeof type === 'string') {
+            return this.generatePrimitiveSchema(type);
+        }
+        // Handle function types (classes, constructors)
+        if (typeof type === 'function') {
+            const typeName = this.getTypeName(type);
+            // Check if already cached
+            if (this.schemas.has(typeName)) {
+                return { $ref: `#/components/schemas/${typeName}` };
+            }
+            // Handle built-in types
+            if (this.isBuiltInType(type)) {
+                return this.generatePrimitiveSchema(type);
+            }
+            // Handle arrays (Array constructor)
+            if (type === Array) {
+                return { type: 'array', items: { type: 'object' } };
+            }
+            // Generate object schema from class
+            return this.generateObjectSchema(type);
+        }
+        // Default fallback
+        return { type: 'object' };
+    }
+    /**
+     * Generate schema for an object/class type
+     * Reads @ApiProperty metadata from class properties
+     */
+    generateObjectSchema(type) {
+        const typeName = this.getTypeName(type);
+        const properties = {};
+        const required = [];
+        // Get all property keys that have @ApiProperty metadata
+        const propertyKeys = getApiPropertyKeys(type.prototype);
+        for (const key of propertyKeys) {
+            const propName = typeof key === 'symbol' ? key.toString() : key;
+            const propOptions = getApiPropertyMetadata(type.prototype, key);
+            if (propOptions) {
+                properties[propName] = this.generatePropertySchema(propOptions);
+                // Track required properties
+                if (propOptions.required !== false) {
+                    required.push(propName);
+                }
+            }
+        }
+        const schema = {
+            type: 'object',
+            properties: Object.keys(properties).length > 0 ? properties : undefined,
+            required: required.length > 0 ? required : undefined,
+        };
+        // Cache the schema
+        this.schemas.set(typeName, schema);
+        // Return a reference to the cached schema
+        return { $ref: `#/components/schemas/${typeName}` };
+    }
+    /**
+     * Generate schema from an @ApiProperty options object
+     */
+    generatePropertySchema(options) {
+        const schema = {};
+        // Type mapping
+        if (options.type) {
+            if (typeof options.type === 'string') {
+                // Map string type names
+                const typeSchema = this.mapStringType(options.type);
+                Object.assign(schema, typeSchema);
+            }
+            else if (typeof options.type === 'function') {
+                // Recurse for class types
+                const nested = this.generateSchema(options.type);
+                Object.assign(schema, nested);
+            }
+        }
+        // String validations
+        if (options.minLength !== undefined)
+            schema.minLength = options.minLength;
+        if (options.maxLength !== undefined)
+            schema.maxLength = options.maxLength;
+        if (options.pattern !== undefined)
+            schema.pattern = options.pattern;
+        // Numeric validations
+        if (options.minimum !== undefined)
+            schema.minimum = options.minimum;
+        if (options.maximum !== undefined)
+            schema.maximum = options.maximum;
+        // Array validations
+        if (options.minItems !== undefined)
+            schema.minItems = options.minItems;
+        if (options.maxItems !== undefined)
+            schema.maxItems = options.maxItems;
+        if (options.items !== undefined)
+            schema.items = options.items;
+        // Enum
+        if (options.enum !== undefined) {
+            schema.enum = options.enum;
+        }
+        // Format
+        if (options.format !== undefined)
+            schema.format = options.format;
+        // Metadata
+        if (options.title !== undefined)
+            schema.title = options.title;
+        if (options.description !== undefined)
+            schema.description = options.description;
+        if (options.example !== undefined)
+            schema.example = options.example;
+        if (options.default !== undefined)
+            schema.default = options.default;
+        if (options.nullable !== undefined)
+            schema.nullable = options.nullable;
+        if (options.readOnly !== undefined)
+            schema.readOnly = options.readOnly;
+        if (options.writeOnly !== undefined)
+            schema.writeOnly = options.writeOnly;
+        return schema;
+    }
+    /**
+     * Generate schema for a primitive TypeScript type
+     */
+    generatePrimitiveSchema(type) {
+        if (typeof type === 'string') {
+            return this.mapStringType(type);
+        }
+        // Map constructor to primitive type
+        if (type === String)
+            return { type: 'string' };
+        if (type === Number)
+            return { type: 'number' };
+        if (type === Boolean)
+            return { type: 'boolean' };
+        if (type === Date)
+            return { type: 'string', format: 'date-time' };
+        if (type === Array)
+            return { type: 'array', items: {} };
+        return { type: 'object' };
+    }
+    /**
+     * Map string type names to OpenAPI schema
+     */
+    mapStringType(type) {
+        switch (type.toLowerCase()) {
+            case 'string':
+                return { type: 'string' };
+            case 'number':
+                return { type: 'number' };
+            case 'integer':
+                return { type: 'integer' };
+            case 'boolean':
+                return { type: 'boolean' };
+            case 'date':
+                return { type: 'string', format: 'date' };
+            case 'datetime':
+            case 'date-time':
+                return { type: 'string', format: 'date-time' };
+            case 'email':
+                return { type: 'string', format: 'email' };
+            case 'uuid':
+                return { type: 'string', format: 'uuid' };
+            case 'url':
+            case 'uri':
+                return { type: 'string', format: 'uri' };
+            case 'object':
+                return { type: 'object' };
+            case 'array':
+                return { type: 'array', items: {} };
+            default:
+                return { type: 'string' };
+        }
+    }
+    /**
+     * Check if type is a built-in TypeScript type
+     */
+    isBuiltInType(type) {
+        return (type === String ||
+            type === Number ||
+            type === Boolean ||
+            type === Date ||
+            type === Array ||
+            type === Object);
+    }
+    /**
+     * Get the name for a type (for referencing in components.schemas)
+     */
+    getTypeName(type) {
+        // Check if we've already assigned a name
+        if (this.typeNames.has(type)) {
+            return this.typeNames.get(type);
+        }
+        // Use the constructor name if available
+        let name = type.name;
+        // Fallback to generic name if no name
+        if (!name || name === 'Object' || name === 'Function') {
+            name = `Schema_${++this.typeCounter}`;
+        }
+        this.typeNames.set(type, name);
+        return name;
+    }
+    /**
+     * Get all generated schemas (for components.schemas)
+     */
+    getSchemas() {
+        const result = {};
+        for (const [name, schema] of this.schemas) {
+            result[name] = schema;
+        }
+        return result;
+    }
+    /**
+     * Clear cached schemas
+     */
+    clear() {
+        this.schemas.clear();
+        this.typeNames.clear();
+        this.typeCounter = 0;
+    }
+}
+//# sourceMappingURL=schema-generator.js.map

package/dist/openapi/schema-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-generator.js","sourceRoot":"","sources":["../../src/openapi/schema-generator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAExE;;GAEG;AACH,MAAM,OAAO,eAAe;IACnB,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC3C,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC3C,WAAW,GAAG,CAAC,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,IAAqC;QACnD,gEAAgE;QAChE,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QAED,gDAAgD;QAChD,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YAExC,0BAA0B;YAC1B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChC,OAAO,EAAE,IAAI,EAAE,wBAAwB,QAAQ,EAAE,EAAE,CAAC;YACrD,CAAC;YAED,wBAAwB;YACxB,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,OAAO,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;YAC3C,CAAC;YAED,oCAAoC;YACpC,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;gBACpB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;YACrD,CAAC;YAED,oCAAoC;YACpC,OAAO,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;QAED,mBAAmB;QACnB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACK,oBAAoB,CAAC,IAAc;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,UAAU,GAAkC,EAAE,CAAC;QACrD,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,wDAAwD;QACxD,MAAM,YAAY,GAAG,kBAAkB,CAAE,IAAoB,CAAC,SAAS,CAAC,CAAC;QAEzE,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;YAChE,MAAM,WAAW,GAAG,sBAAsB,CACxC,IAAoB,CAAC,SAAS,EAC/B,GAAG,CACH,CAAC;YAEF,IAAI,WAAW,EAAE,CAAC;gBACjB,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC;gBAEhE,4BAA4B;gBAC5B,IAAI,WAAW,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;oBACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACzB,CAAC;YACF,CAAC;QACF,CAAC;QAED,MAAM,MAAM,GAAkB;YAC7B,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YACvE,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SACpD,CAAC;QAEF,mBAAmB;QACnB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAEnC,0CAA0C;QAC1C,OAAO,EAAE,IAAI,EAAE,wBAAwB,QAAQ,EAAE,EAAE,CAAC;IACrD,CAAC;IAED;;OAEG;IACK,sBAAsB,CAAC,OAA2B;QACzD,MAAM,MAAM,GAAkB,EAAE,CAAC;QAEjC,eAAe;QACf,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAClB,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtC,wBAAwB;gBACxB,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACpD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YACnC,CAAC;iBAAM,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC/C,0BAA0B;gBAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACjD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC/B,CAAC;QACF,CAAC;QAED,qBAAqB;QACrB,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;YAAE,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAC1E,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;YAAE,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAC1E,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAEpE,sBAAsB;QACtB,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACpE,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAEpE,oBAAoB;QACpB,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACvE,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACvE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAE9D,OAAO;QACP,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC5B,CAAC;QAED,SAAS;QACT,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAEjE,WAAW;QACX,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC9D,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QAChF,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACpE,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACpE,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACvE,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACvE,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;YAAE,MAAM,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAE1E,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;OAEG;IACK,uBAAuB,CAAC,IAAuB;QACtD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;QAED,oCAAoC;QACpC,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC/C,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC/C,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACjD,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAClE,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAExD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,IAAY;QACjC,QAAQ,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YAC5B,KAAK,QAAQ;gBACZ,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3B,KAAK,QAAQ;gBACZ,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3B,KAAK,SAAS;gBACb,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC5B,KAAK,SAAS;gBACb,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC5B,KAAK,MAAM;gBACV,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YAC3C,KAAK,UAAU,CAAC;YAChB,KAAK,WAAW;gBACf,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;YAChD,KAAK,OAAO;gBACX,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;YAC5C,KAAK,MAAM;gBACV,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YAC3C,KAAK,KAAK,CAAC;YACX,KAAK,KAAK;gBACT,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YAC1C,KAAK,QAAQ;gBACZ,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3B,KAAK,OAAO;gBACX,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YACrC;gBACC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC5B,CAAC;IACF,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,IAAc;QACnC,OAAO,CACN,IAAI,KAAK,MAAM;YACf,IAAI,KAAK,MAAM;YACf,IAAI,KAAK,OAAO;YAChB,IAAI,KAAK,IAAI;YACb,IAAI,KAAK,KAAK;YACd,IAAI,KAAK,MAAM,CACf,CAAC;IACH,CAAC;IAED;;OAEG;IACK,WAAW,CAAC,IAAc;QACjC,yCAAyC;QACzC,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAmB,CAAC,EAAE,CAAC;YAC7C,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAmB,CAAE,CAAC;QACjD,CAAC;QAED,wCAAwC;QACxC,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAErB,sCAAsC;QACtC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACvD,IAAI,GAAG,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAmB,EAAE,IAAI,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;OAEG;IACH,UAAU;QACT,MAAM,MAAM,GAAkC,EAAE,CAAC;QACjD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QACvB,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK;QACJ,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;IACtB,CAAC;CACD"}

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

@@ -0,0 +1,57 @@
+/**
+ * Swagger Module
+ *
+ * Provides utilities to set up Swagger UI and integrate OpenAPI document generation
+ * with a Bueno Application.
+ */
+import type { Application } from '../modules';
+import type { Constructor, OpenAPIDocument, SwaggerOptions } from './types';
+/**
+ * SwaggerModule - Static utilities for OpenAPI integration
+ */
+export declare class SwaggerModule {
+    /**
+     * Create an OpenAPI document from a Bueno Application and controllers
+     *
+     * @param app - The Application instance
+     * @param config - Base OpenAPI document configuration
+     * @param controllers - Array of controller classes to scan
+     * @returns Complete OpenAPI document with paths and schemas
+     *
+     * @example
+     * ```typescript
+     * const document = SwaggerModule.createDocument(app, {
+     *   openapi: '3.1.0',
+     *   info: { title: 'My API', version: '1.0.0' },
+     *   paths: {},
+     * }, [UserController, PostController]);
+     * ```
+     */
+    static createDocument(app: Application, config: OpenAPIDocument, controllers: Constructor[]): OpenAPIDocument;
+    /**
+     * Setup Swagger UI and JSON endpoint
+     *
+     * Registers two routes:
+     * - GET {path} - Swagger UI HTML page
+     * - GET {path}-json - OpenAPI JSON document
+     *
+     * @param path - Base path for Swagger UI (e.g., '/api-docs')
+     * @param app - The Application instance
+     * @param document - OpenAPI document to serve
+     * @param options - Swagger UI configuration options
+     *
+     * @example
+     * ```typescript
+     * const document = SwaggerModule.createDocument(app, config, controllers);
+     * SwaggerModule.setup('/api-docs', app, document, {
+     *   title: 'My API Documentation',
+     * });
+     * ```
+     */
+    static setup(path: string, app: Application, document: OpenAPIDocument, options?: SwaggerOptions): void;
+    /**
+     * Generate Swagger UI HTML
+     */
+    private static generateSwaggerUI;
+}
+//# sourceMappingURL=swagger-module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"swagger-module.d.ts","sourceRoot":"","sources":["../../src/openapi/swagger-module.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK5E;;GAEG;AACH,qBAAa,aAAa;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,cAAc,CACpB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,WAAW,EAAE,GACxB,eAAe;IAyBlB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,CACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,cAAc,GACtB,IAAI;IAaP;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;CA6DhC"}