nestjs-openapi 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,896 @@
+import { Effect, Context, Layer, Option } from 'effect';
+import { C as ConfigNotFoundError, O as OpenApiGeneratorConfig, a as ConfigError, R as ResolvedConfig, P as ProjectError, b as ProjectInitError, E as EntryNotFoundError, M as MethodInfo, c as OpenApiPaths$1 } from './shared/nestjs-openapi.BYUrTaMo.js';
+export { A as AnalysisError, i as ConfigLoadError, j as ConfigValidationError, G as GenerateOptions, k as GeneratorError, H as HttpMethod, I as InvalidMethodError, e as ParameterLocation, f as ResolvedParameter, h as ReturnTypeInfo, d as generateAsync, g as generateEffect } from './shared/nestjs-openapi.BYUrTaMo.js';
+import { DynamicModule } from '@nestjs/common';
+import { Project, SourceFile, ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
+
+/**
+ * Public types for nestjs-openapi
+ *
+ * These types are exposed to consumers of the library. Internal types
+ * should be kept in domain.ts.
+ */
+/**
+ * Contact information for the API
+ */
+interface ContactConfig {
+    readonly name?: string;
+    readonly email?: string;
+    readonly url?: string;
+}
+/**
+ * License information for the API
+ */
+interface LicenseConfig {
+    readonly name: string;
+    readonly url?: string;
+}
+/**
+ * API metadata for the OpenAPI info section
+ */
+interface InfoConfig {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly contact?: ContactConfig;
+    readonly license?: LicenseConfig;
+}
+/**
+ * Server configuration for the OpenAPI servers section
+ */
+interface ServerConfig {
+    readonly url: string;
+    readonly description?: string;
+}
+/**
+ * Tag configuration for organizing API endpoints
+ */
+interface TagConfig {
+    readonly name: string;
+    readonly description?: string;
+}
+/**
+ * Security scheme type for OpenAPI 3.0
+ */
+type SecuritySchemeType = 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
+/**
+ * Location for apiKey security schemes
+ */
+type SecuritySchemeIn = 'query' | 'header' | 'cookie';
+/**
+ * OAuth2 flow configuration
+ */
+interface OAuth2FlowConfig {
+    readonly authorizationUrl?: string;
+    readonly tokenUrl?: string;
+    readonly refreshUrl?: string;
+    readonly scopes?: Record<string, string>;
+}
+/**
+ * OAuth2 flows configuration
+ */
+interface OAuth2FlowsConfig {
+    readonly implicit?: OAuth2FlowConfig;
+    readonly password?: OAuth2FlowConfig;
+    readonly clientCredentials?: OAuth2FlowConfig;
+    readonly authorizationCode?: OAuth2FlowConfig;
+}
+/**
+ * Security scheme configuration for OpenAPI 3.0
+ *
+ * @example
+ * ```typescript
+ * // Bearer token (JWT)
+ * {
+ *   name: 'bearerAuth',
+ *   type: 'http',
+ *   scheme: 'bearer',
+ *   bearerFormat: 'JWT',
+ * }
+ *
+ * // API Key in header
+ * {
+ *   name: 'apiKey',
+ *   type: 'apiKey',
+ *   in: 'header',
+ *   parameterName: 'X-API-Key',
+ * }
+ *
+ * // OAuth2
+ * {
+ *   name: 'oauth2',
+ *   type: 'oauth2',
+ *   flows: {
+ *     authorizationCode: {
+ *       authorizationUrl: 'https://example.com/oauth/authorize',
+ *       tokenUrl: 'https://example.com/oauth/token',
+ *       scopes: { 'read:users': 'Read user data' },
+ *     },
+ *   },
+ * }
+ * ```
+ */
+interface SecuritySchemeConfig {
+    /** Unique name for this security scheme (used as key in securitySchemes) */
+    readonly name: string;
+    /** The type of the security scheme */
+    readonly type: SecuritySchemeType;
+    /** Description of the security scheme */
+    readonly description?: string;
+    /** The name of the HTTP Authorization scheme (for type: 'http') */
+    readonly scheme?: string;
+    /** A hint for the format of the token (for type: 'http' with scheme: 'bearer') */
+    readonly bearerFormat?: string;
+    /** The location of the API key (for type: 'apiKey') */
+    readonly in?: SecuritySchemeIn;
+    /** The name of the header, query, or cookie parameter (for type: 'apiKey') */
+    readonly parameterName?: string;
+    /** OAuth2 flows configuration (for type: 'oauth2') */
+    readonly flows?: OAuth2FlowsConfig;
+    /** OpenID Connect URL to discover OAuth2 config (for type: 'openIdConnect') */
+    readonly openIdConnectUrl?: string;
+}
+/**
+ * Security requirement - maps security scheme names to required scopes
+ *
+ * @example
+ * ```typescript
+ * // Require bearerAuth with no specific scopes
+ * { bearerAuth: [] }
+ *
+ * // Require oauth2 with specific scopes
+ * { oauth2: ['read:users', 'write:users'] }
+ * ```
+ */
+type SecurityRequirement = Record<string, readonly string[]>;
+/**
+ * Output format for the generated OpenAPI specification
+ */
+type OutputFormat = 'json' | 'yaml';
+/**
+ * OpenAPI specification version
+ * - '3.0.3': OpenAPI 3.0.3 (default, widely supported)
+ * - '3.1.0': OpenAPI 3.1.0 (full JSON Schema 2020-12 alignment, type arrays for nullable)
+ * - '3.2.0': OpenAPI 3.2.0 (when released, will include webhooks and other new features)
+ */
+type OpenApiVersion = '3.0.3' | '3.1.0' | '3.2.0';
+/**
+ * Input file configuration for nestjs-openapi.
+ * All paths are relative to the config file location.
+ */
+interface FilesConfig {
+    /**
+     * Entry module file(s).
+     * @default "src/app.module.ts"
+     */
+    readonly entry?: string | readonly string[];
+    /**
+     * Path to tsconfig.json. Auto-detected if not specified.
+     */
+    readonly tsconfig?: string;
+    /**
+     * Glob pattern(s) for DTO files to generate schemas from.
+     * @example "src/**\/*.dto.ts"
+     */
+    readonly dtoGlob?: string | readonly string[];
+    /**
+     * Glob patterns to include.
+     */
+    readonly include?: readonly string[];
+    /**
+     * Glob patterns to exclude.
+     * @default ["**\/*.spec.ts", "**\/*.test.ts", "**\/node_modules/**"]
+     */
+    readonly exclude?: readonly string[];
+}
+/**
+ * Security configuration for OpenAPI spec.
+ */
+interface SecurityConfig {
+    /**
+     * Security schemes available for the API.
+     * Defines authentication methods (bearer, apiKey, oauth2, etc.)
+     */
+    readonly schemes?: readonly SecuritySchemeConfig[];
+    /**
+     * Global security requirements applied to all operations.
+     * Can be overridden at the operation level.
+     * Each object in the array represents an alternative (OR logic).
+     * Within each object, all schemes must be satisfied (AND logic).
+     *
+     * @example
+     * ```typescript
+     * // Require bearerAuth for all operations
+     * global: [{ bearerAuth: [] }]
+     *
+     * // Allow either bearerAuth OR apiKey
+     * global: [{ bearerAuth: [] }, { apiKey: [] }]
+     * ```
+     */
+    readonly global?: readonly SecurityRequirement[];
+}
+/**
+ * OpenAPI specification metadata configuration.
+ * Maps directly to the OpenAPI spec structure.
+ */
+interface OpenApiConfig {
+    /**
+     * OpenAPI specification version.
+     * @default "3.0.3"
+     */
+    readonly version?: OpenApiVersion;
+    /**
+     * API metadata for the info section.
+     * @required
+     */
+    readonly info: InfoConfig;
+    /**
+     * Server URLs for the API.
+     */
+    readonly servers?: readonly ServerConfig[];
+    /**
+     * Tags for organizing API endpoints.
+     */
+    readonly tags?: readonly TagConfig[];
+    /**
+     * Security configuration.
+     */
+    readonly security?: SecurityConfig;
+}
+/**
+ * Generation behavior options.
+ */
+interface OptionsConfig {
+    /**
+     * Base path prefix for all routes.
+     * Equivalent to NestJS's app.setGlobalPrefix().
+     * @example "/api/v1"
+     */
+    readonly basePath?: string;
+    /**
+     * Extract validation constraints from class-validator decorators.
+     * @default true
+     */
+    readonly extractValidation?: boolean;
+    /**
+     * Decorator names that exclude endpoints from the spec.
+     * @default ["ApiExcludeEndpoint", "ApiExcludeController"]
+     */
+    readonly excludeDecorators?: readonly string[];
+    /**
+     * Filter paths by regex or predicate function.
+     * Paths matching the regex (or returning true) are INCLUDED.
+     *
+     * @example
+     * ```typescript
+     * // Exclude internal and versioned paths
+     * pathFilter: /^(?!.*(\/internal\/|\/v[\d.]+\/)).* /
+     *
+     * // Using a function
+     * pathFilter: (path) => !path.includes('/internal/')
+     * ```
+     */
+    readonly pathFilter?: RegExp | ((path: string) => boolean);
+    /**
+     * Query parameter handling options.
+     */
+    readonly query?: QueryOptions;
+}
+/**
+ * Query parameter handling options.
+ */
+interface QueryOptions {
+    /**
+     * How to represent query object DTOs (e.g., `@Query() dto: PaginationDto`).
+     * - `"inline"` (default): Expand DTO properties as individual query parameters
+     * - `"ref"`: Keep as a single parameter with a schema reference
+     *
+     * @default "inline"
+     *
+     * @example
+     * ```typescript
+     * // With style: "inline" (default)
+     * // @Query() dto: PaginationDto becomes:
+     * // - page: integer (query)
+     * // - limit: integer (query)
+     *
+     * // With style: "ref"
+     * // @Query() dto: PaginationDto becomes:
+     * // - dto: $ref to PaginationDto schema (query)
+     * ```
+     */
+    readonly style?: 'inline' | 'ref';
+}
+/**
+ * Configuration for nestjs-openapi.
+ * Inspired by tsconfig.json and vite.config.ts patterns.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from 'nestjs-openapi';
+ *
+ * export default defineConfig({
+ *   output: 'src/openapi/openapi.generated.json',
+ *
+ *   files: {
+ *     entry: 'src/app.module.ts',
+ *     dtoGlob: 'src/**\/*.dto.ts',
+ *   },
+ *
+ *   openapi: {
+ *     info: {
+ *       title: 'My API',
+ *       version: '1.0.0',
+ *     },
+ *   },
+ *
+ *   options: {
+ *     basePath: '/api',
+ *     extractValidation: true,
+ *   },
+ * });
+ * ```
+ */
+interface Config {
+    /**
+     * Extend another config file. Paths are relative to this config file.
+     * Extended config values are deeply merged, with this config taking precedence.
+     * @example extends: './configs/base-openapi.config.ts'
+     */
+    readonly extends?: string;
+    /**
+     * Input file configuration.
+     * All paths are relative to the config file location.
+     */
+    readonly files?: FilesConfig;
+    /**
+     * Output path for the generated OpenAPI specification.
+     * Path is relative to the config file location.
+     * @required
+     */
+    readonly output: string;
+    /**
+     * Output format for the specification.
+     * @default "json"
+     */
+    readonly format?: OutputFormat;
+    /**
+     * OpenAPI specification metadata.
+     * Maps directly to the OpenAPI spec structure.
+     * @required
+     */
+    readonly openapi: OpenApiConfig;
+    /**
+     * Generation behavior options.
+     */
+    readonly options?: OptionsConfig;
+}
+/**
+ * Options for the generate function to override config values.
+ * Useful for CLI overrides.
+ */
+interface GenerateOverrides {
+    /**
+     * Override the output format.
+     * Takes precedence over config.format.
+     */
+    readonly format?: OutputFormat;
+    /**
+     * Enable debug mode for verbose logging and full stack traces.
+     */
+    readonly debug?: boolean;
+}
+/**
+ * OpenAPI 3.0/3.1/3.2 specification schema object
+ * Type can be a string or array of strings (for nullable in 3.1+)
+ */
+interface OpenApiSchema {
+    /** Schema type - string or array for 3.1+ nullable (e.g., ['string', 'null']) */
+    readonly type?: string | readonly string[];
+    readonly format?: string;
+    readonly $ref?: string;
+    readonly oneOf?: readonly OpenApiSchema[];
+    readonly anyOf?: readonly OpenApiSchema[];
+    readonly allOf?: readonly OpenApiSchema[];
+    readonly items?: OpenApiSchema;
+    readonly properties?: Record<string, OpenApiSchema>;
+    readonly required?: readonly string[];
+    readonly enum?: readonly unknown[];
+    readonly description?: string;
+    /** OpenAPI 3.0 only - use type: [T, 'null'] in 3.1+ instead */
+    readonly nullable?: boolean;
+    /** Examples array for 3.1+ (replaces single 'example' field) */
+    readonly examples?: readonly unknown[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly exclusiveMaximum?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly default?: unknown;
+    readonly additionalProperties?: boolean | OpenApiSchema;
+}
+/**
+ * OpenAPI 3.0 parameter object
+ */
+interface OpenApiParameter {
+    readonly name: string;
+    readonly in: 'path' | 'query' | 'header' | 'cookie';
+    readonly description?: string;
+    readonly required: boolean;
+    readonly schema: OpenApiSchema;
+}
+/**
+ * OpenAPI 3.0 request body object
+ */
+interface OpenApiRequestBody {
+    readonly description?: string;
+    readonly required?: boolean;
+    readonly content: Record<string, {
+        readonly schema: OpenApiSchema;
+    }>;
+}
+/**
+ * OpenAPI 3.0 response object
+ */
+interface OpenApiResponse {
+    readonly description: string;
+    readonly content?: Record<string, {
+        readonly schema: OpenApiSchema;
+    }>;
+}
+/**
+ * OpenAPI 3.0 operation object
+ */
+interface OpenApiOperation {
+    readonly operationId: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly deprecated?: boolean;
+    readonly tags?: readonly string[];
+    readonly parameters?: readonly OpenApiParameter[];
+    readonly requestBody?: OpenApiRequestBody;
+    readonly responses: Record<string, OpenApiResponse>;
+    /** Per-operation security requirements (overrides global security) */
+    readonly security?: readonly SecurityRequirement[];
+}
+/**
+ * OpenAPI 3.0 paths object
+ * Maps path patterns to HTTP method operations
+ */
+interface OpenApiPaths {
+    readonly [path: string]: {
+        readonly [method: string]: OpenApiOperation;
+    };
+}
+/**
+ * OpenAPI 3.0 OAuth2 flow object
+ */
+interface OpenApiOAuth2Flow {
+    readonly authorizationUrl?: string;
+    readonly tokenUrl?: string;
+    readonly refreshUrl?: string;
+    readonly scopes: Record<string, string>;
+}
+/**
+ * OpenAPI 3.0 OAuth2 flows object
+ */
+interface OpenApiOAuth2Flows {
+    readonly implicit?: OpenApiOAuth2Flow;
+    readonly password?: OpenApiOAuth2Flow;
+    readonly clientCredentials?: OpenApiOAuth2Flow;
+    readonly authorizationCode?: OpenApiOAuth2Flow;
+}
+/**
+ * OpenAPI 3.0 security scheme object
+ */
+interface OpenApiSecurityScheme {
+    readonly type: SecuritySchemeType;
+    readonly description?: string;
+    /** The name of the HTTP Authorization scheme (for type: 'http') */
+    readonly scheme?: string;
+    /** A hint for the format of the token (for type: 'http' with scheme: 'bearer') */
+    readonly bearerFormat?: string;
+    /** The location of the API key (for type: 'apiKey') */
+    readonly in?: SecuritySchemeIn;
+    /** The name of the header, query, or cookie parameter (for type: 'apiKey') */
+    readonly name?: string;
+    /** OAuth2 flows (for type: 'oauth2') */
+    readonly flows?: OpenApiOAuth2Flows;
+    /** OpenID Connect URL (for type: 'openIdConnect') */
+    readonly openIdConnectUrl?: string;
+}
+/**
+ * Webhook operation for OpenAPI 3.1+
+ * Similar to regular operations but accessed via events rather than HTTP methods
+ */
+interface OpenApiWebhookOperation {
+    readonly post?: OpenApiOperation;
+    readonly put?: OpenApiOperation;
+    readonly patch?: OpenApiOperation;
+    readonly delete?: OpenApiOperation;
+    readonly get?: OpenApiOperation;
+}
+/**
+ * Complete OpenAPI 3.0/3.1/3.2 specification
+ */
+interface OpenApiSpec {
+    readonly openapi: OpenApiVersion;
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description?: string;
+        readonly contact?: ContactConfig;
+        readonly license?: LicenseConfig;
+    };
+    readonly servers?: readonly ServerConfig[];
+    readonly tags?: readonly TagConfig[];
+    readonly paths: OpenApiPaths;
+    /** Webhooks for OpenAPI 3.1+ - event-driven operations */
+    readonly webhooks?: Record<string, OpenApiWebhookOperation>;
+    readonly components?: {
+        readonly schemas?: Record<string, OpenApiSchema>;
+        readonly securitySchemes?: Record<string, OpenApiSecurityScheme>;
+    };
+    /** Global security requirements */
+    readonly security?: readonly SecurityRequirement[];
+}
+
+/**
+ * OpenAPI spec validation utilities.
+ *
+ * Validates that generated specs don't have broken $ref references
+ * or other common issues.
+ */
+
+/**
+ * A broken reference found during validation
+ */
+interface BrokenRef {
+    /** The $ref value that couldn't be resolved */
+    readonly ref: string;
+    /** The JSON path where this reference was found */
+    readonly path: string;
+    /** The schema name that's missing (extracted from $ref) */
+    readonly missingSchema: string;
+}
+/**
+ * Result of spec validation
+ */
+interface ValidationResult {
+    /** Whether the spec is valid (no broken refs) */
+    readonly valid: boolean;
+    /** Total number of schema refs found */
+    readonly totalRefs: number;
+    /** Number of broken refs */
+    readonly brokenRefCount: number;
+    /** Details of each broken ref */
+    readonly brokenRefs: readonly BrokenRef[];
+    /** Missing schema names grouped with their usage count */
+    readonly missingSchemas: ReadonlyMap<string, number>;
+}
+/**
+ * Validates an OpenAPI spec for broken $ref references.
+ *
+ * @param spec - The OpenAPI specification to validate
+ * @returns Validation result with details about any broken refs
+ *
+ * @example
+ * ```typescript
+ * const result = validateSpec(spec);
+ * if (!result.valid) {
+ *   console.error(`Found ${result.brokenRefCount} broken refs:`);
+ *   for (const [schema, count] of result.missingSchemas) {
+ *     console.error(`  - ${schema} (${count} usages)`);
+ *   }
+ * }
+ * ```
+ */
+declare function validateSpec(spec: OpenApiSpec): ValidationResult;
+/**
+ * Categorizes broken refs by likely cause
+ */
+interface BrokenRefCategories {
+    /** Primitive types that shouldn't be refs (string, number, boolean) */
+    readonly primitives: readonly string[];
+    /** Union types (Type | null, void | Type) */
+    readonly unionTypes: readonly string[];
+    /** Query/Path parameter DTOs */
+    readonly queryParams: readonly string[];
+    /** Other missing schemas (likely from different glob patterns) */
+    readonly other: readonly string[];
+}
+/**
+ * Categorize broken refs to help diagnose the root cause.
+ *
+ * @param missingSchemas - Map of missing schema names to usage count
+ * @returns Categorized broken refs
+ */
+declare function categorizeBrokenRefs(missingSchemas: ReadonlyMap<string, number>): BrokenRefCategories;
+/**
+ * Formats validation result as a human-readable string for CLI output.
+ *
+ * @param result - Validation result from validateSpec
+ * @returns Formatted string describing the validation issues
+ */
+declare function formatValidationResult(result: ValidationResult): string;
+
+/**
+ * Promise-based entry point for generating OpenAPI specifications.
+ *
+ * This module provides a clean, Promise-based API that hides the internal
+ * Effect-TS implementation from consumers.
+ */
+
+interface GenerateResult {
+    /** Path where the OpenAPI spec was written */
+    readonly outputPath: string;
+    /** Number of paths in the generated spec */
+    readonly pathCount: number;
+    /** Number of operations in the generated spec */
+    readonly operationCount: number;
+    /** Number of schemas in the generated spec */
+    readonly schemaCount: number;
+    /** Validation result checking for broken refs */
+    readonly validation: ValidationResult;
+}
+/**
+ * Generates an OpenAPI specification from a NestJS application.
+ *
+ * @param configPath - Path to the configuration file (openapi.config.ts)
+ * @param options - Optional overrides for config values (e.g., format)
+ * @returns Promise that resolves with generation result when complete
+ *
+ * @example
+ * ```typescript
+ * import { generate } from 'nestjs-openapi';
+ *
+ * await generate('apps/backend-api/openapi.config.ts');
+ *
+ * // Override format from CLI
+ * await generate('apps/backend-api/openapi.config.ts', { format: 'yaml' });
+ * ```
+ */
+declare const generate: (configPath: string, overrides?: GenerateOverrides) => Promise<GenerateResult>;
+
+/**
+ * Define configuration for OpenAPI generation.
+ *
+ * @example
+ * ```typescript
+ * export default defineConfig({
+ *   output: 'openapi.json',
+ *   files: { entry: 'src/app.module.ts' },
+ *   openapi: { info: { title: 'My API', version: '1.0.0' } },
+ * });
+ * ```
+ */
+declare function defineConfig(config: Config): Config;
+declare const findConfigFile: (startDir?: string) => Effect.Effect<string, ConfigNotFoundError>;
+declare const loadConfigFromFile: (configPath: string) => Effect.Effect<typeof OpenApiGeneratorConfig.Type, ConfigError>;
+declare const loadConfig: (configPath?: string, cwd?: string) => Effect.Effect<typeof OpenApiGeneratorConfig.Type, ConfigError>;
+declare const resolveConfig: (config: typeof OpenApiGeneratorConfig.Type) => typeof ResolvedConfig.Type;
+declare const loadAndResolveConfig: (configPath?: string, cwd?: string) => Effect.Effect<typeof ResolvedConfig.Type, ConfigError>;
+
+/**
+ * NestJS Module for serving generated OpenAPI specifications at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { OpenApiModule } from 'nestjs-openapi';
+ *
+ * @Module({
+ *   imports: [
+ *     OpenApiModule.forRoot({
+ *       specFile: 'openapi.json',
+ *       swagger: true,
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+
+/**
+ * Swagger UI configuration options
+ */
+interface SwaggerOptions {
+    /**
+     * The path where Swagger UI will be served.
+     * @default "/api-docs"
+     */
+    readonly path?: string;
+    /**
+     * Custom title for the Swagger UI page.
+     * Uses the spec's info.title if not provided.
+     */
+    readonly title?: string;
+}
+/**
+ * Configuration options for the OpenAPI module
+ */
+interface OpenApiModuleOptions {
+    /**
+     * Path to the generated OpenAPI JSON file.
+     * Can be absolute or relative to the current working directory.
+     */
+    readonly specFile: string;
+    /**
+     * Whether the module is enabled.
+     * When false, no routes are registered.
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /**
+     * The path where the OpenAPI JSON will be served.
+     * @default "/openapi.json"
+     */
+    readonly jsonPath?: string;
+    /**
+     * Swagger UI configuration.
+     * - `true` - Enable with defaults (path: '/api-docs', title from spec)
+     * - `false` or omitted - Disable Swagger UI
+     * - `object` - Enable with custom configuration
+     * @default false
+     */
+    readonly swagger?: boolean | SwaggerOptions;
+}
+/**
+ * Resolved options with all defaults applied
+ */
+interface ResolvedOpenApiModuleOptions {
+    readonly specFile: string;
+    readonly enabled: boolean;
+    readonly jsonPath: string;
+    readonly swagger: {
+        readonly enabled: boolean;
+        readonly path: string;
+        readonly title: string;
+    };
+}
+/**
+ * Injection token for OpenAPI module options
+ */
+declare const OPENAPI_MODULE_OPTIONS: unique symbol;
+/**
+ * Injection token for the loaded OpenAPI specification
+ */
+declare const OPENAPI_SPEC: unique symbol;
+/**
+ * Generate Swagger UI HTML page
+ */
+declare function generateSwaggerUiHtml(title: string, jsonPath: string): string;
+/**
+ * Load the OpenAPI spec file from disk
+ */
+declare function loadSpecFile(filePath: string): OpenApiSpec;
+/**
+ * Resolve options with defaults
+ */
+declare function resolveOptions(options: OpenApiModuleOptions): ResolvedOpenApiModuleOptions;
+/**
+ * NestJS module for serving generated OpenAPI specifications at runtime.
+ *
+ * This module provides:
+ * - JSON endpoint for the OpenAPI specification
+ * - Optional Swagger UI for interactive documentation
+ * - Conditional enabling based on environment
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - serve JSON only
+ * OpenApiModule.forRoot({
+ *   specFile: 'openapi.json',
+ * })
+ *
+ * // With Swagger UI (defaults)
+ * OpenApiModule.forRoot({
+ *   specFile: 'openapi.json',
+ *   swagger: true,
+ * })
+ *
+ * // With Swagger UI (custom options)
+ * OpenApiModule.forRoot({
+ *   specFile: 'openapi.json',
+ *   swagger: { path: '/docs', title: 'My API' },
+ * })
+ *
+ * // Conditionally enabled
+ * OpenApiModule.forRoot({
+ *   specFile: 'openapi.json',
+ *   enabled: process.env.OPENAPI_ENABLED === 'true',
+ * })
+ * ```
+ */
+declare class OpenApiModule {
+    /**
+     * Configure the OpenAPI module with options.
+     *
+     * @param options - Configuration options
+     * @returns Dynamic module configuration
+     */
+    static forRoot(options: OpenApiModuleOptions): DynamicModule;
+}
+
+interface ProjectContext {
+    readonly project: Project;
+    readonly entrySourceFile: SourceFile;
+    readonly entryClass: ClassDeclaration;
+}
+interface ProjectOptions {
+    readonly tsconfig: string;
+    readonly entry: string;
+}
+declare const ProjectService_base: Context.TagClass<ProjectService, "ProjectService", {
+    readonly context: ProjectContext;
+}>;
+/**
+ * ProjectService is an infrastructure context holder.
+ * Context.Tag is appropriate here as it holds externally-provided resources.
+ */
+declare class ProjectService extends ProjectService_base {
+}
+declare const makeProjectContext: (options: ProjectOptions) => Effect.Effect<{
+    project: Project;
+    entrySourceFile: SourceFile;
+    entryClass: ClassDeclaration;
+}, ProjectInitError | EntryNotFoundError, never>;
+declare const ProjectServiceLive: (options: ProjectOptions) => Layer.Layer<ProjectService, ProjectError>;
+
+interface ModuleWithControllers {
+    readonly declaration: ClassDeclaration;
+    readonly controllers: readonly ClassDeclaration[];
+}
+/** Iterative BFS to avoid stack overflow on deep module graphs */
+declare const getModules: (root: ClassDeclaration) => Effect.Effect<readonly ModuleWithControllers[], never, never>;
+declare const getAllControllers: (root: ClassDeclaration) => Effect.Effect<ClassDeclaration[], never, never>;
+
+declare const normalizePath: (path: string) => string;
+declare const getControllerPrefix: (controller: ClassDeclaration) => string;
+declare const getControllerName: (controller: ClassDeclaration) => string;
+declare const isHttpMethod: (method: MethodDeclaration) => boolean;
+declare const getHttpMethods: (controller: ClassDeclaration) => readonly MethodDeclaration[];
+/** Handles both @Get and @Get() syntax */
+declare const getDecoratorName: (decorator: Decorator) => string;
+/** Falls back to controller name (minus 'Controller' suffix) if no @ApiTags */
+declare const getControllerTags: (controller: ClassDeclaration) => readonly string[];
+declare const isHttpDecorator: (decorator: Decorator) => boolean;
+declare const getHttpDecorator: (method: MethodDeclaration) => Decorator | undefined;
+
+/** Configuration options for parameter extraction */
+interface ExtractParametersOptions {
+    /** Query parameter handling options */
+    readonly query?: {
+        /** How to represent query DTOs: "inline" (default) or "ref" */
+        readonly style?: 'inline' | 'ref';
+    };
+}
+/** Returns None if the method has no HTTP decorator */
+declare const getMethodInfo: (controller: ClassDeclaration, method: MethodDeclaration, options?: ExtractParametersOptions) => Option.Option<MethodInfo>;
+declare const getControllerMethodInfos: (controller: ClassDeclaration, options?: ExtractParametersOptions) => readonly MethodInfo[];
+
+declare const transformMethod: (methodInfo: MethodInfo) => OpenApiPaths$1;
+declare const transformMethods: (methodInfos: readonly MethodInfo[]) => OpenApiPaths$1;
+
+/** Handles aliased symbols (re-exports) */
+declare const resolveClassFromSymbol: (sym: Symbol) => Option.Option<ClassDeclaration>;
+declare const getArrayInitializer: (objectLiteral: ObjectLiteralExpression, propertyName: string) => Option.Option<Expression>;
+declare const getStringLiteralValue: (expr: Expression | undefined) => Option.Option<string>;
+declare const getSymbolFromIdentifier: (expr: Expression | undefined) => Option.Option<Symbol>;
+
+declare const isModuleClass: (cls: ClassDeclaration | undefined) => boolean;
+declare const getModuleDecoratorArg: (cls: ClassDeclaration) => Option.Option<ObjectLiteralExpression>;
+/** Handles identifiers, forwardRef(() => Class), and property access */
+declare const resolveClassFromExpression: (expr: Expression | undefined) => Option.Option<ClassDeclaration>;
+declare const resolveArrayOfClasses: (propInit?: Expression) => readonly ClassDeclaration[];
+interface ModuleMetadata {
+    readonly controllers: readonly ClassDeclaration[];
+    readonly imports: readonly ClassDeclaration[];
+}
+declare const getModuleMetadata: (mod: ClassDeclaration) => ModuleMetadata;
+
+export { ConfigError, ConfigNotFoundError, EntryNotFoundError, MethodInfo, OPENAPI_MODULE_OPTIONS, OPENAPI_SPEC, OpenApiGeneratorConfig, OpenApiModule, ProjectError, ProjectInitError, ProjectService, ProjectServiceLive, ResolvedConfig, categorizeBrokenRefs, defineConfig, findConfigFile, formatValidationResult, generate, generateSwaggerUiHtml, getAllControllers, getArrayInitializer, getControllerMethodInfos, getControllerName, getControllerPrefix, getControllerTags, getDecoratorName, getHttpDecorator, getHttpMethods, getMethodInfo, getModuleDecoratorArg, getModuleMetadata, getModules, getStringLiteralValue, getSymbolFromIdentifier, isHttpDecorator, isHttpMethod, isModuleClass, loadAndResolveConfig, loadConfig, loadConfigFromFile, loadSpecFile, makeProjectContext, normalizePath, resolveArrayOfClasses, resolveClassFromExpression, resolveClassFromSymbol, resolveConfig, resolveOptions, transformMethod, transformMethods, validateSpec };
+export type { BrokenRef, BrokenRefCategories, Config, ContactConfig, GenerateOverrides, GenerateResult, InfoConfig, LicenseConfig, ModuleMetadata, ModuleWithControllers, OpenApiModuleOptions, OpenApiOperation, OpenApiParameter, OpenApiPaths, OpenApiRequestBody, OpenApiResponse, OpenApiSchema, OpenApiSpec, OutputFormat, ProjectContext, ProjectOptions, ResolvedOpenApiModuleOptions, ServerConfig, SwaggerOptions, TagConfig, ValidationResult };