@buenojs/bueno 0.8.3 → 0.8.5

package/src/openapi/route-scanner.ts

@@ -0,0 +1,289 @@
+/**
+ * Route Scanner
+ *
+ * Scans controllers and extracts OpenAPI operation metadata from decorators.
+ * Combines HTTP method decorators, parameter documentation, and responses
+ * into OpenAPI operation objects.
+ */
+
+import type {
+	Constructor,
+	OpenAPIMediaType,
+	OpenAPIOperation,
+	OpenAPIPaths,
+	OpenAPIResponse,
+	OpenAPISchema,
+} from './types';
+import { getApiMetadata, getApiMethodMetadata } from './metadata';
+// Read controller path and route list from the modules metadata stores
+import { getMetadata, getPrototypeMetadata } from '../modules/metadata';
+import { SchemaGenerator } from './schema-generator';
+
+interface RouteInfo {
+	method: string;
+	path: string;
+	handler: string | symbol;
+}
+
+/**
+ * RouteScanner - Scans controllers and extracts OpenAPI operations
+ */
+export class RouteScanner {
+	constructor(private schemaGenerator: SchemaGenerator) {}
+
+	/**
+	 * Scan all controllers and generate OpenAPI paths
+	 */
+	scanControllers(controllers: Constructor[]): OpenAPIPaths {
+		const paths: OpenAPIPaths = {};
+
+		for (const controller of controllers) {
+			// Skip controllers marked with @ApiExcludeController
+			if (getApiMetadata<boolean>(controller, 'api:exclude')) {
+				continue;
+			}
+
+			// Get controller base path from @Controller decorator (stored in modules metadata)
+			const basePath = getMetadata<string>(controller, 'path') ?? '';
+
+			// Get routes from prototype metadata (stored by @Get, @Post, etc. in modules metadata)
+			const routes =
+				getPrototypeMetadata<RouteInfo[]>(controller.prototype, 'routes') ?? [];
+
+			// Get class-level tags and security from OpenAPI metadata
+			const classLevelTags = getApiMetadata<string[]>(controller, 'api:tags') ?? [];
+			const classLevelSecurity =
+				getApiMetadata<Record<string, string[]>[]>(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<boolean>(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] as Record<string, OpenAPIOperation>)[
+					route.method.toLowerCase()
+				] = operation;
+			}
+		}
+
+		return paths;
+	}
+
+	/**
+	 * Generate an OpenAPI operation for a single route
+	 */
+	private generateOperation(
+		controller: Constructor,
+		route: RouteInfo,
+		classLevelTags: string[],
+		classLevelSecurity: Record<string, string[]>[],
+		basePath: string,
+	): OpenAPIOperation {
+		const prototype = controller.prototype;
+		const handlerKey = String(route.handler);
+
+		// Helper to read per-method OpenAPI metadata — stored under "api:<key>:<handler>"
+		const getMethodMeta = <T>(key: string): T | undefined =>
+			getApiMethodMetadata<T>(prototype, `${key}:${handlerKey}`);
+
+		// Get operation metadata from decorators
+		const operationMeta = getMethodMeta<{
+			summary?: string;
+			description?: string;
+			operationId?: string;
+			deprecated?: boolean;
+		}>('api:operation');
+
+		const responseMeta =
+			getMethodMeta<
+				Array<{
+					status: number | 'default';
+					description: string;
+					type?: Constructor | Constructor[];
+					schema?: OpenAPISchema;
+				}>
+			>('api:responses') ?? [];
+
+		const paramMeta =
+			getMethodMeta<
+				Array<{
+					name: string;
+					type?: string;
+					description?: string;
+					required?: boolean;
+					example?: unknown;
+					schema?: OpenAPISchema;
+				}>
+			>('api:params') ?? [];
+
+		const queryMeta =
+			getMethodMeta<
+				Array<{
+					name: string;
+					type?: string;
+					description?: string;
+					required?: boolean;
+					example?: unknown;
+					schema?: OpenAPISchema;
+				}>
+			>('api:query') ?? [];
+
+		const headerMeta =
+			getMethodMeta<
+				Array<{
+					name: string;
+					description?: string;
+					required?: boolean;
+					schema?: OpenAPISchema;
+				}>
+			>('api:headers') ?? [];
+
+		const bodyMeta = getMethodMeta<{
+			type?: Constructor;
+			description?: string;
+			required?: boolean;
+			schema?: OpenAPISchema;
+		}>('api:body');
+
+		const methodLevelTags = getMethodMeta<string[]>('api:tags') ?? [];
+
+		const methodLevelSecurity =
+			getMethodMeta<Record<string, string[]>[]>('api:security') ?? [];
+
+		// Build parameters array
+		const parameters = [
+			...paramMeta.map((p) => ({
+				name: p.name,
+				in: 'path' as const,
+				description: p.description,
+				required: p.required ?? true,
+				example: p.example,
+				schema: p.schema,
+			})),
+			...queryMeta.map((q) => ({
+				name: q.name,
+				in: 'query' as const,
+				description: q.description,
+				required: q.required ?? false,
+				example: q.example,
+				schema: q.schema,
+			})),
+			...headerMeta.map((h) => ({
+				name: h.name,
+				in: 'header' as const,
+				description: h.description,
+				required: h.required,
+				schema: h.schema,
+			})),
+		];
+
+		// Build responses object (properly typed)
+		const responses: Record<string, OpenAPIResponse> = {};
+
+		for (const resp of responseMeta) {
+			const statusCode = String(resp.status);
+			const response: OpenAPIResponse = { description: resp.description };
+
+			// Add schema if provided
+			if (resp.type || resp.schema) {
+				let schema: OpenAPISchema = 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: OpenAPIMediaType = { 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' as const }),
+						} satisfies OpenAPIMediaType,
+					},
+				}
+			: 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: OpenAPIOperation = {
+			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>)
+	 */
+	private convertPathToOpenAPI(pattern: string): string {
+		return pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)\??(?:<[^>]+>)?/g, '{$1}');
+	}
+
+	/**
+	 * Get the schema generator instance
+	 */
+	getSchemaGenerator(): SchemaGenerator {
+		return this.schemaGenerator;
+	}
+}

package/src/openapi/schema-generator.ts

@@ -0,0 +1,256 @@
+/**
+ * Schema Generator
+ *
+ * Converts TypeScript class types and @ApiProperty decorators into OpenAPI schemas.
+ */
+
+import type { ApiPropertyOptions, Constructor, OpenAPISchema } from './types';
+import { getApiPropertyMetadata, getApiPropertyKeys } from './metadata';
+
+/**
+ * SchemaGenerator - Converts TypeScript types to OpenAPI schemas
+ */
+export class SchemaGenerator {
+	private schemas = new Map<string, OpenAPISchema>();
+	private typeNames = new Map<Constructor, string>();
+	private typeCounter = 0;
+
+	/**
+	 * Generate an OpenAPI schema from a TypeScript type
+	 * Supports classes, interfaces (via decorators), primitives, arrays
+	 */
+	generateSchema(type: Constructor | string | Function): OpenAPISchema {
+		// 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
+	 */
+	private generateObjectSchema(type: Function): OpenAPISchema {
+		const typeName = this.getTypeName(type);
+		const properties: Record<string, OpenAPISchema> = {};
+		const required: string[] = [];
+
+		// Get all property keys that have @ApiProperty metadata
+		const propertyKeys = getApiPropertyKeys((type as Constructor).prototype);
+
+		for (const key of propertyKeys) {
+			const propName = typeof key === 'symbol' ? key.toString() : key;
+			const propOptions = getApiPropertyMetadata<ApiPropertyOptions>(
+				(type as Constructor).prototype,
+				key,
+			);
+
+			if (propOptions) {
+				properties[propName] = this.generatePropertySchema(propOptions);
+
+				// Track required properties
+				if (propOptions.required !== false) {
+					required.push(propName);
+				}
+			}
+		}
+
+		const schema: OpenAPISchema = {
+			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
+	 */
+	private generatePropertySchema(options: ApiPropertyOptions): OpenAPISchema {
+		const schema: OpenAPISchema = {};
+
+		// 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
+	 */
+	private generatePrimitiveSchema(type: string | Function): OpenAPISchema {
+		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
+	 */
+	private mapStringType(type: string): OpenAPISchema {
+		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
+	 */
+	private isBuiltInType(type: Function): boolean {
+		return (
+			type === String ||
+			type === Number ||
+			type === Boolean ||
+			type === Date ||
+			type === Array ||
+			type === Object
+		);
+	}
+
+	/**
+	 * Get the name for a type (for referencing in components.schemas)
+	 */
+	private getTypeName(type: Function): string {
+		// Check if we've already assigned a name
+		if (this.typeNames.has(type as Constructor)) {
+			return this.typeNames.get(type as Constructor)!;
+		}
+
+		// 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 as Constructor, name);
+		return name;
+	}
+
+	/**
+	 * Get all generated schemas (for components.schemas)
+	 */
+	getSchemas(): Record<string, OpenAPISchema> {
+		const result: Record<string, OpenAPISchema> = {};
+		for (const [name, schema] of this.schemas) {
+			result[name] = schema;
+		}
+		return result;
+	}
+
+	/**
+	 * Clear cached schemas
+	 */
+	clear(): void {
+		this.schemas.clear();
+		this.typeNames.clear();
+		this.typeCounter = 0;
+	}
+}

package/src/openapi/swagger-module.ts

@@ -0,0 +1,166 @@
+/**
+ * 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';
+import { DocumentBuilder } from './document-builder';
+import { RouteScanner } from './route-scanner';
+import { SchemaGenerator } from './schema-generator';
+
+/**
+ * SwaggerModule - Static utilities for OpenAPI integration
+ */
+export 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 {
+		const schemaGenerator = new SchemaGenerator();
+		const scanner = new RouteScanner(schemaGenerator);
+
+		// Scan controllers to get paths and schemas
+		const paths = scanner.scanControllers(controllers);
+		const schemas = schemaGenerator.getSchemas();
+
+		// Merge with the provided config
+		return {
+			...config,
+			paths: {
+				...config.paths,
+				...paths,
+			},
+			components: {
+				...config.components,
+				schemas: {
+					...(config.components?.schemas ?? {}),
+					...schemas,
+				},
+			},
+		};
+	}
+
+	/**
+	 * 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 {
+		// Register JSON endpoint
+		app.router.get(`${path}-json`, (ctx) => {
+			return ctx.json(document);
+		});
+
+		// Register Swagger UI endpoint
+		app.router.get(path, (ctx) => {
+			const html = this.generateSwaggerUI(path, document, options);
+			return ctx.html(html);
+		});
+	}
+
+	/**
+	 * Generate Swagger UI HTML
+	 */
+	private static generateSwaggerUI(
+		jsonPath: string,
+		document: OpenAPIDocument,
+		options?: SwaggerOptions,
+	): string {
+		const title = options?.title ?? 'API Documentation';
+		const customCss = options?.customCss ?? '';
+		const customSiteTitle = options?.customSiteTitle ?? title;
+		const favicon = options?.customfavIcon ?? '';
+
+		return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${customSiteTitle}</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *, *:before, *:after {
+      box-sizing: inherit;
+    }
+    body {
+      margin: 0;
+      padding: 0;
+      font-family: sans-serif;
+    }
+    ${customCss}
+  </style>
+  ${favicon ? `<link rel="icon" href="${favicon}">` : ''}
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+  <script>
+    window.onload = function() {
+      SwaggerUIBundle({
+        url: '${jsonPath}-json',
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: 'StandaloneLayout',
+        defaultModelsExpandDepth: 1,
+        defaultModelExpandDepth: 1,
+      });
+    };
+  </script>
+</body>
+</html>`;
+	}
+}