@buenojs/bueno 0.8.4 → 0.8.5

package/src/openapi/document-builder.ts

@@ -0,0 +1,274 @@
+/**
+ * OpenAPI Document Builder
+ *
+ * Fluent API for building OpenAPI 3.1 documents with configuration for
+ * servers, security schemes, tags, and other top-level metadata.
+ */
+
+import type {
+	ApiKeySecurityOptions,
+	OpenAPIComponents,
+	OpenAPIDocument,
+	OpenAPISecurityScheme,
+	OpenAPIServer,
+	OpenAPITag,
+	SecuritySchemeOptions,
+} from './types';
+
+/**
+ * DocumentBuilder - Fluent API for constructing OpenAPI documents
+ *
+ * @example
+ * ```typescript
+ * const document = new DocumentBuilder()
+ *   .setTitle('My API')
+ *   .setVersion('1.0.0')
+ *   .setDescription('API description')
+ *   .addBearerAuth()
+ *   .addTag('users', 'User management endpoints')
+ *   .build();
+ * ```
+ */
+export class DocumentBuilder {
+	private document: Partial<OpenAPIDocument> = {
+		openapi: '3.1.0',
+		info: {
+			title: 'API',
+			version: '1.0.0',
+		},
+		paths: {},
+		components: {
+			schemas: {},
+			securitySchemes: {},
+		},
+		tags: [],
+	};
+
+	/**
+	 * Set the API title
+	 */
+	setTitle(title: string): this {
+		if (!this.document.info) {
+			this.document.info = { title, version: '1.0.0' };
+		} else {
+			this.document.info.title = title;
+		}
+		return this;
+	}
+
+	/**
+	 * Set the API description
+	 */
+	setDescription(description: string): this {
+		if (!this.document.info) {
+			this.document.info = { title: 'API', version: '1.0.0', description };
+		} else {
+			this.document.info.description = description;
+		}
+		return this;
+	}
+
+	/**
+	 * Set the API version
+	 */
+	setVersion(version: string): this {
+		if (!this.document.info) {
+			this.document.info = { title: 'API', version };
+		} else {
+			this.document.info.version = version;
+		}
+		return this;
+	}
+
+	/**
+	 * Set contact information
+	 */
+	setContact(name: string, url?: string, email?: string): this {
+		if (!this.document.info) {
+			this.document.info = { title: 'API', version: '1.0.0' };
+		}
+		this.document.info.contact = { name, url, email };
+		return this;
+	}
+
+	/**
+	 * Set license information
+	 */
+	setLicense(name: string, url?: string): this {
+		if (!this.document.info) {
+			this.document.info = { title: 'API', version: '1.0.0' };
+		}
+		this.document.info.license = { name, url };
+		return this;
+	}
+
+	/**
+	 * Add a server
+	 */
+	addServer(url: string, description?: string): this {
+		if (!this.document.servers) {
+			this.document.servers = [];
+		}
+		this.document.servers.push({ url, description });
+		return this;
+	}
+
+	/**
+	 * Add Bearer token authentication
+	 *
+	 * @example
+	 * ```typescript
+	 * builder.addBearerAuth('JWT')
+	 * ```
+	 */
+	addBearerAuth(
+		name = 'bearer',
+		options?: SecuritySchemeOptions,
+	): this {
+		if (!this.document.components) {
+			this.document.components = { schemas: {}, securitySchemes: {} };
+		}
+		if (!this.document.components.securitySchemes) {
+			this.document.components.securitySchemes = {};
+		}
+
+		const scheme: OpenAPISecurityScheme = {
+			type: 'http',
+			scheme: 'bearer',
+			bearerFormat: options?.bearerFormat ?? 'JWT',
+		};
+
+		if (options?.description) {
+			scheme.description = options.description;
+		}
+
+		this.document.components.securitySchemes[name] = scheme;
+		return this;
+	}
+
+	/**
+	 * Add Basic authentication
+	 */
+	addBasicAuth(name = 'basic', options?: SecuritySchemeOptions): this {
+		if (!this.document.components) {
+			this.document.components = { schemas: {}, securitySchemes: {} };
+		}
+		if (!this.document.components.securitySchemes) {
+			this.document.components.securitySchemes = {};
+		}
+
+		const scheme: OpenAPISecurityScheme = {
+			type: 'http',
+			scheme: 'basic',
+		};
+
+		if (options?.description) {
+			scheme.description = options.description;
+		}
+
+		this.document.components.securitySchemes[name] = scheme;
+		return this;
+	}
+
+	/**
+	 * Add API Key authentication
+	 */
+	addApiKey(
+		options: ApiKeySecurityOptions,
+		name = 'api_key',
+	): this {
+		if (!this.document.components) {
+			this.document.components = { schemas: {}, securitySchemes: {} };
+		}
+		if (!this.document.components.securitySchemes) {
+			this.document.components.securitySchemes = {};
+		}
+
+		const scheme: OpenAPISecurityScheme = {
+			type: 'apiKey',
+			name: options.name,
+			in: options.in,
+		};
+
+		if (options.description) {
+			scheme.description = options.description;
+		}
+
+		this.document.components.securitySchemes[name] = scheme;
+		return this;
+	}
+
+	/**
+	 * Add an OAuth2 security scheme
+	 */
+	addOAuth2(
+		name: string,
+		authorizationUrl: string,
+		tokenUrl?: string,
+		refreshUrl?: string,
+	): this {
+		if (!this.document.components) {
+			this.document.components = { schemas: {}, securitySchemes: {} };
+		}
+		if (!this.document.components.securitySchemes) {
+			this.document.components.securitySchemes = {};
+		}
+
+		this.document.components.securitySchemes[name] = {
+			type: 'oauth2',
+			flows: {
+				authorizationCode: {
+					authorizationUrl,
+					tokenUrl: tokenUrl || '',
+					refreshUrl,
+					scopes: {},
+				},
+			},
+		};
+
+		return this;
+	}
+
+	/**
+	 * Add an OpenID Connect security scheme
+	 */
+	addOpenIdConnect(name: string, url: string): this {
+		if (!this.document.components) {
+			this.document.components = { schemas: {}, securitySchemes: {} };
+		}
+		if (!this.document.components.securitySchemes) {
+			this.document.components.securitySchemes = {};
+		}
+
+		this.document.components.securitySchemes[name] = {
+			type: 'openIdConnect',
+			openIdConnectUrl: url,
+		};
+
+		return this;
+	}
+
+	/**
+	 * Add a tag for organizing operations
+	 */
+	addTag(name: string, description?: string): this {
+		if (!this.document.tags) {
+			this.document.tags = [];
+		}
+
+		const tag: OpenAPITag = { name };
+		if (description) {
+			tag.description = description;
+		}
+
+		this.document.tags.push(tag);
+		return this;
+	}
+
+	/**
+	 * Build and return the final OpenAPI document
+	 */
+	build(): OpenAPIDocument {
+		return this.document as OpenAPIDocument;
+	}
+}

package/src/openapi/index.ts

@@ -0,0 +1,112 @@
+/**
+ * OpenAPI Module
+ *
+ * Auto-generate OpenAPI 3.1 specifications from Bueno controllers and decorators.
+ * Provides decorators for documenting API endpoints and a SwaggerModule for setup.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DocumentBuilder,
+ *   SwaggerModule,
+ *   ApiOperation,
+ *   ApiResponse,
+ *   ApiTags,
+ * } from '@buenojs/bueno/openapi';
+ *
+ * // 1. Document your controller
+ * @Controller('/users')
+ * @ApiTags('users')
+ * class UsersController {
+ *   @Get()
+ *   @ApiOperation({ summary: 'List all users' })
+ *   @ApiResponse({ status: 200, description: 'Success', type: [User] })
+ *   async getAll() { ... }
+ * }
+ *
+ * // 2. Create OpenAPI document
+ * const config = new DocumentBuilder()
+ *   .setTitle('My API')
+ *   .setVersion('1.0.0')
+ *   .addBearerAuth()
+ *   .build();
+ *
+ * const document = SwaggerModule.createDocument(app, config, [UsersController]);
+ *
+ * // 3. Setup Swagger UI
+ * SwaggerModule.setup('/api-docs', app, document);
+ * ```
+ */
+
+// ============= Type Exports =============
+
+export type {
+	OpenAPIDocument,
+	OpenAPIInfo,
+	OpenAPIContact,
+	OpenAPILicense,
+	OpenAPIServer,
+	OpenAPIPaths,
+	OpenAPIPath,
+	OpenAPIOperation,
+	OpenAPIExternalDocs,
+	OpenAPIParameter,
+	OpenAPIRequestBody,
+	OpenAPIMediaType,
+	OpenAPIExample,
+	OpenAPIResponse,
+	OpenAPIHeader,
+	OpenAPIResponses,
+	OpenAPISchema,
+	OpenAPIDiscriminator,
+	OpenAPIXML,
+	OpenAPIComponents,
+	OpenAPISecurityScheme,
+	OpenAPIOAuthFlows,
+	OpenAPIOAuthFlow,
+	OpenAPISecurity,
+	OpenAPITag,
+	SwaggerOptions,
+	ApiOperationOptions,
+	ApiResponseOptions,
+	ApiParamOptions,
+	ApiQueryOptions,
+	ApiHeaderOptions,
+	ApiBodyOptions,
+	ApiPropertyOptions,
+	SecuritySchemeOptions,
+	ApiKeySecurityOptions,
+	Constructor,
+} from './types';
+
+// ============= Class Exports =============
+
+export { DocumentBuilder } from './document-builder';
+export { SchemaGenerator } from './schema-generator';
+export { RouteScanner } from './route-scanner';
+export { SwaggerModule } from './swagger-module';
+
+// ============= Decorator Exports =============
+
+// Class-level decorators
+export {
+	ApiTags,
+	ApiBearerAuth,
+	ApiBasicAuth,
+	ApiApiKey,
+	ApiExcludeController,
+} from './decorators';
+
+// Method-level decorators
+export {
+	ApiOperation,
+	ApiResponse,
+	ApiParam,
+	ApiQuery,
+	ApiHeader,
+	ApiBody,
+	ApiExcludeEndpoint,
+} from './decorators';
+
+// Property-level decorators (for DTOs)
+export { ApiProperty, ApiPropertyOptional } from './decorators';

package/src/openapi/metadata.ts

@@ -0,0 +1,112 @@
+/**
+ * OpenAPI Metadata Storage
+ *
+ * Isolated metadata storage using WeakMap, following the same pattern as src/modules/metadata.ts
+ * This avoids circular dependencies and keeps metadata separate from the core module system.
+ */
+
+import type { Constructor } from './types';
+
+// ============= Class-Level Metadata =============
+
+/**
+ * Stores metadata on class constructors (e.g., @ApiTags, @ApiBearerAuth, @ApiExcludeController)
+ */
+const classMetadataStore = new WeakMap<Constructor, Map<string, unknown>>();
+
+/**
+ * Set metadata on a class constructor
+ */
+export function setApiMetadata(
+	target: Constructor,
+	key: string,
+	value: unknown,
+): void {
+	if (!classMetadataStore.has(target)) {
+		classMetadataStore.set(target, new Map());
+	}
+	classMetadataStore.get(target)?.set(key, value);
+}
+
+/**
+ * Get metadata from a class constructor
+ */
+export function getApiMetadata<T>(
+	target: Constructor,
+	key: string,
+): T | undefined {
+	return classMetadataStore.get(target)?.get(key) as T | undefined;
+}
+
+// ============= Method/Prototype-Level Metadata =============
+
+/**
+ * Stores metadata on method prototypes (e.g., @ApiOperation, @ApiResponse, @ApiParam)
+ */
+const methodMetadataStore = new WeakMap<object, Map<string, unknown>>();
+
+/**
+ * Set metadata on a method prototype
+ */
+export function setApiMethodMetadata(
+	target: object,
+	key: string,
+	value: unknown,
+): void {
+	if (!methodMetadataStore.has(target)) {
+		methodMetadataStore.set(target, new Map());
+	}
+	methodMetadataStore.get(target)?.set(key, value);
+}
+
+/**
+ * Get metadata from a method prototype
+ */
+export function getApiMethodMetadata<T>(
+	target: object,
+	key: string,
+): T | undefined {
+	return methodMetadataStore.get(target)?.get(key) as T | undefined;
+}
+
+// ============= Property-Level Metadata =============
+
+/**
+ * Stores metadata on class properties (e.g., @ApiProperty decorators on DTO properties)
+ */
+const propertyMetadataStore = new WeakMap<object, Map<string, unknown>>();
+
+/**
+ * Set metadata on a property of a class prototype
+ */
+export function setApiPropertyMetadata(
+	target: object,
+	propertyKey: string | symbol,
+	value: unknown,
+): void {
+	if (!propertyMetadataStore.has(target)) {
+		propertyMetadataStore.set(target, new Map());
+	}
+	const key = typeof propertyKey === 'symbol' ? propertyKey.toString() : propertyKey;
+	propertyMetadataStore.get(target)?.set(key, value);
+}
+
+/**
+ * Get metadata from a property of a class prototype
+ */
+export function getApiPropertyMetadata<T>(
+	target: object,
+	propertyKey: string | symbol,
+): T | undefined {
+	const key = typeof propertyKey === 'symbol' ? propertyKey.toString() : propertyKey;
+	return propertyMetadataStore.get(target)?.get(key) as T | undefined;
+}
+
+/**
+ * Get all property metadata keys from a class prototype
+ */
+export function getApiPropertyKeys(target: object): (string | symbol)[] {
+	const metaMap = propertyMetadataStore.get(target);
+	if (!metaMap) return [];
+	return Array.from(metaMap.keys()) as (string | symbol)[];
+}