nestjs-openapi 0.2.2 → 0.3.0

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import 'tsx';
 import { Effect, Exit, Cause, Option } from 'effect';
-import { ax as generateEffect, ak as generatorServicesLayer, az as runtimeLayerFor, aw as formatValidationResult } from './shared/nestjs-openapi.DeikubMm.mjs';
+import { ax as generateEffect, ak as generatorServicesLayer, az as runtimeLayerFor, aw as formatValidationResult } from './shared/nestjs-openapi.Nd-wGr8A.mjs';
 import minimist from 'minimist';
 import { relative } from 'node:path';
 import { createRequire } from 'node:module';

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { O as OpenApiSpec, S as SpecFileNotFoundError, a as SpecFileReadError, b as SpecFileParseError, M as MethodInfo, c as OpenApiPaths, d as OpenApiOperation, e as OpenApiPaths$1, G as GeneratedSchemas, f as OpenApiSchema, g as OutputService, h as SchemaService, V as ValidationService, C as ConfigService, i as ModuleTraversalService, j as MethodExtractionService, P as ProjectService } from './shared/nestjs-openapi.NtbZNAvU.mjs';
-export { a4 as AnalysisError, aJ as BrokenRef, aK as BrokenRefCategories, az as ClassValidationInfo, n as Config, a3 as ConfigError, X as ConfigLoadError, W as ConfigNotFoundError, Y as ConfigValidationError, o as ContactConfig, Z as DtoGlobResolutionError, U as EntryNotFoundError, E as GenerateOptions, s as GenerateOverrides, l as GenerateResult, a5 as GeneratorError, J as HttpMethod, I as InfoConfig, _ as InvalidMethodError, am as JsonSchema, L as LicenseConfig, $ as MissingGenericSchemaTempFileCleanupError, a0 as MissingGenericSchemaTempFileWriteError, ac as ModuleWithControllers, K as OpenApiGeneratorConfig, t as OpenApiOperation, u as OpenApiParameter, v as OpenApiRequestBody, w as OpenApiResponse, q as OutputFormat, F as ParameterLocation, a8 as ProjectContext, a2 as ProjectError, Q as ProjectInitError, a9 as ProjectOptions, a6 as ProjectServiceLive, ay as PropertyValidationInfo, a1 as PublicApiError, N as ResolvedConfig, R as ResolvedParameter, H as ReturnTypeInfo, ak as SchemaError, aj as SchemaGenerationError, al as SchemaGeneratorOptions, p as ServerConfig, T as TagConfig, r as TelemetryConfig, ax as ValidationConstraints, aI as ValidationResult, au as applyConstraintsToSchema, aG as categorizeBrokenRefs, m as defineConfig, as as extractClassConstraints, aq as extractClassValidationInfo, ar as extractClassValidationInfoEffect, an as extractPropertyConstraints, ap as extractPropertyValidationInfo, aA as findConfigFile, aH as formatValidationResult, k as generate, y as generateAsync, x as generateEffect, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect, ah as generateSchemas, ai as generateSchemasFromFiles, ab as getAllControllers, af as getControllerMethodInfos, ag as getControllerMethodInfosEffect, ad as getMethodInfo, ae as getMethodInfoEffect, aa as getModules, at as getRequiredProperties, ao as isPropertyOptional, aE as loadAndResolveConfig, aC as loadConfig, aB as loadConfigFromFile, a7 as makeProjectContext, av as mergeValidationConstraints, aw as mergeValidationConstraintsEffect, aD as resolveConfig, aF as validateSpec } from './shared/nestjs-openapi.NtbZNAvU.mjs';
+import { O as OpenApiSpec, S as SpecFileNotFoundError, a as SpecFileReadError, b as SpecFileParseError, M as MethodInfo, c as OpenApiPaths, d as OpenApiOperation, e as OpenApiPaths$1, G as GeneratedSchemas, f as OpenApiSchema, P as ProjectService, g as ModuleTraversalService, C as ConfigService, h as SchemaService, V as ValidationService, i as MethodExtractionService, j as OutputService } from './shared/nestjs-openapi.CAanamW0.mjs';
+export { a4 as AnalysisError, aJ as BrokenRef, aK as BrokenRefCategories, az as ClassValidationInfo, n as Config, a3 as ConfigError, X as ConfigLoadError, W as ConfigNotFoundError, Y as ConfigValidationError, o as ContactConfig, Z as DtoGlobResolutionError, U as EntryNotFoundError, E as GenerateOptions, s as GenerateOverrides, l as GenerateResult, a5 as GeneratorError, J as HttpMethod, I as InfoConfig, _ as InvalidMethodError, am as JsonSchema, L as LicenseConfig, $ as MissingGenericSchemaTempFileCleanupError, a0 as MissingGenericSchemaTempFileWriteError, ac as ModuleWithControllers, K as OpenApiGeneratorConfig, t as OpenApiOperation, u as OpenApiParameter, v as OpenApiRequestBody, w as OpenApiResponse, q as OutputFormat, F as ParameterLocation, a8 as ProjectContext, a2 as ProjectError, Q as ProjectInitError, a9 as ProjectOptions, a6 as ProjectServiceLive, ay as PropertyValidationInfo, a1 as PublicApiError, N as ResolvedConfig, R as ResolvedParameter, H as ReturnTypeInfo, ak as SchemaError, aj as SchemaGenerationError, al as SchemaGeneratorOptions, p as ServerConfig, T as TagConfig, r as TelemetryConfig, ax as ValidationConstraints, aI as ValidationResult, au as applyConstraintsToSchema, aG as categorizeBrokenRefs, m as defineConfig, as as extractClassConstraints, aq as extractClassValidationInfo, ar as extractClassValidationInfoEffect, an as extractPropertyConstraints, ap as extractPropertyValidationInfo, aA as findConfigFile, aH as formatValidationResult, k as generate, y as generateAsync, x as generateEffect, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect, ah as generateSchemas, ai as generateSchemasFromFiles, ab as getAllControllers, af as getControllerMethodInfos, ag as getControllerMethodInfosEffect, ad as getMethodInfo, ae as getMethodInfoEffect, aa as getModules, at as getRequiredProperties, ao as isPropertyOptional, aE as loadAndResolveConfig, aC as loadConfig, aB as loadConfigFromFile, a7 as makeProjectContext, av as mergeValidationConstraints, aw as mergeValidationConstraintsEffect, aD as resolveConfig, aF as validateSpec } from './shared/nestjs-openapi.CAanamW0.mjs';
 import { DynamicModule } from '@nestjs/common';
 import { Effect, Option, Layer } from 'effect';
 import { ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
@@ -38,10 +38,24 @@ interface SwaggerOptions {
      */
     readonly title?: string;
 }
+interface LoadSpecFileOptions {
+    /**
+     * Additional spec files to try when the primary file is missing.
+     */
+    readonly fallbackSpecFiles?: readonly string[];
+}
+interface OpenApiDocumentFileSource extends LoadSpecFileOptions {
+    /**
+     * Path to the generated OpenAPI JSON file.
+     * Can be absolute or relative to the current working directory.
+     */
+    readonly specFile: string;
+}
+type OpenApiDocumentSource = OpenApiSpec | (() => OpenApiSpec) | OpenApiDocumentFileSource;
 /**
  * Configuration options for the OpenAPI module
  */
-interface OpenApiModuleOptions {
+interface OpenApiModuleOptions extends LoadSpecFileOptions {
     /**
      * Path to the generated OpenAPI JSON file.
      * Can be absolute or relative to the current working directory.
@@ -72,6 +86,7 @@ interface OpenApiModuleOptions {
  */
 interface ResolvedOpenApiModuleOptions {
     readonly specFile: string;
+    readonly fallbackSpecFiles: readonly string[];
     readonly enabled: boolean;
     readonly jsonPath: string;
     readonly swagger: {
@@ -88,6 +103,52 @@ declare const OPENAPI_MODULE_OPTIONS: unique symbol;
  * Injection token for the loaded OpenAPI specification
  */
 declare const OPENAPI_SPEC: unique symbol;
+interface OpenApiRouteRegistrar {
+    readonly get: (path: string, handler: (request: unknown, response: unknown) => void) => void;
+}
+interface OpenApiHttpApplication {
+    readonly config?: {
+        readonly getGlobalPrefix?: () => string;
+    };
+    readonly getHttpAdapter: () => OpenApiRouteRegistrar;
+}
+interface OpenApiSetupOptions {
+    /**
+     * Whether OpenAPI routes should be registered.
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /**
+     * Prefix OpenAPI routes with the app's `setGlobalPrefix()` value.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.useGlobalPrefix`.
+     * @default false
+     */
+    readonly useGlobalPrefix?: boolean;
+    /**
+     * Raw OpenAPI JSON endpoint path.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.jsonDocumentUrl`.
+     * @default `${docsPath}-json`
+     */
+    readonly jsonDocumentUrl?: string;
+    /**
+     * Whether Swagger UI should be served.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.ui`.
+     * @default true
+     */
+    readonly ui?: boolean;
+    /**
+     * Whether raw OpenAPI definitions should be served.
+     * Only JSON is supported.
+     * @default true
+     */
+    readonly raw?: boolean | readonly 'json'[];
+    /**
+     * Browser title for Swagger UI.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.customSiteTitle`.
+     * Uses the spec's info.title if not provided.
+     */
+    readonly customSiteTitle?: string;
+}
 /**
  * Generate Swagger UI HTML page
  */
@@ -95,8 +156,8 @@ declare function generateSwaggerUiHtml(title: string, jsonPath: string): string;
 /**
  * Load the OpenAPI spec file from disk
  */
-declare const loadSpecFileEffect: (filePath: string) => Effect.Effect<OpenApiSpec, SpecFileNotFoundError | SpecFileReadError | SpecFileParseError, never>;
-declare function loadSpecFile(filePath: string): OpenApiSpec;
+declare const loadSpecFileEffect: (filePath: string, options?: LoadSpecFileOptions | undefined) => Effect.Effect<OpenApiSpec, SpecFileNotFoundError | SpecFileReadError | SpecFileParseError, never>;
+declare function loadSpecFile(filePath: string, options?: LoadSpecFileOptions): OpenApiSpec;
 /**
  * Resolve options with defaults
  */
@@ -143,6 +204,13 @@ declare class OpenApiModule {
      * @returns Dynamic module configuration
      */
     static forRoot(options: OpenApiModuleOptions): DynamicModule;
+    /**
+     * Register OpenAPI JSON and Swagger UI routes on an already-created Nest app.
+     *
+     * Use this when the route config depends on services that are only available
+     * during bootstrap. For module-level static config, prefer `forRoot()`.
+     */
+    static setup(path: string, app: OpenApiHttpApplication, documentSource: OpenApiDocumentSource, options?: OpenApiSetupOptions): void;
 }
 
 declare const normalizePath: (path: string) => string;
@@ -159,8 +227,12 @@ declare const getHttpDecorator: (method: MethodDeclaration) => Decorator | undef
 
 declare const transformMethod: (methodInfo: MethodInfo) => OpenApiPaths;
 declare const transformMethodEffect: (methodInfo: {
-    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
+    readonly security: readonly {
+        readonly scopes: readonly string[];
+        readonly schemeName: string;
+    }[];
     readonly path: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly methodName: string;
     readonly controllerName: string;
     readonly controllerTags: readonly string[];
@@ -172,10 +244,10 @@ declare const transformMethodEffect: (methodInfo: {
     };
     readonly parameters: readonly {
         readonly name: string;
-        readonly location: "path" | "query" | "header" | "cookie" | "body";
+        readonly description: Option.Option<string>;
+        readonly location: "query" | "header" | "cookie" | "path" | "body";
         readonly tsType: string;
         readonly required: boolean;
-        readonly description: Option.Option<string>;
     }[];
     readonly decorators: readonly string[];
     readonly operation: {
@@ -185,18 +257,14 @@ declare const transformMethodEffect: (methodInfo: {
         readonly deprecated: Option.Option<boolean>;
     };
     readonly responses: readonly {
-        readonly type: Option.Option<string>;
         readonly description: Option.Option<string>;
+        readonly type: Option.Option<string>;
         readonly statusCode: number;
         readonly isArray: boolean;
     }[];
     readonly httpCode: Option.Option<number>;
     readonly consumes: readonly string[];
     readonly produces: readonly string[];
-    readonly security: readonly {
-        readonly schemeName: string;
-        readonly scopes: readonly string[];
-    }[];
 }) => Effect.Effect<OpenApiPaths, never, never>;
 type MutableOpenApiPaths = {
     [path: string]: {
@@ -205,8 +273,12 @@ type MutableOpenApiPaths = {
 };
 declare const transformMethods: (methodInfos: readonly MethodInfo[]) => OpenApiPaths;
 declare const transformMethodsEffect: (methodInfos: readonly {
-    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
+    readonly security: readonly {
+        readonly scopes: readonly string[];
+        readonly schemeName: string;
+    }[];
     readonly path: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly methodName: string;
     readonly controllerName: string;
     readonly controllerTags: readonly string[];
@@ -218,10 +290,10 @@ declare const transformMethodsEffect: (methodInfos: readonly {
     };
     readonly parameters: readonly {
         readonly name: string;
-        readonly location: "path" | "query" | "header" | "cookie" | "body";
+        readonly description: Option.Option<string>;
+        readonly location: "query" | "header" | "cookie" | "path" | "body";
         readonly tsType: string;
         readonly required: boolean;
-        readonly description: Option.Option<string>;
     }[];
     readonly decorators: readonly string[];
     readonly operation: {
@@ -231,18 +303,14 @@ declare const transformMethodsEffect: (methodInfos: readonly {
         readonly deprecated: Option.Option<boolean>;
     };
     readonly responses: readonly {
-        readonly type: Option.Option<string>;
         readonly description: Option.Option<string>;
+        readonly type: Option.Option<string>;
         readonly statusCode: number;
         readonly isArray: boolean;
     }[];
     readonly httpCode: Option.Option<number>;
     readonly consumes: readonly string[];
     readonly produces: readonly string[];
-    readonly security: readonly {
-        readonly schemeName: string;
-        readonly scopes: readonly string[];
-    }[];
 }[]) => Effect.Effect<MutableOpenApiPaths, never, never>;
 
 /**
@@ -309,7 +377,7 @@ declare const normalizeStructureRefsEffect: (schemas: GeneratedSchemas) => Effec
 /**
  * Shared service dependency graph for generation pipelines.
  */
-declare const generatorServicesLayer: Layer.Layer<OutputService | SchemaService | ValidationService | ConfigService | ModuleTraversalService | MethodExtractionService | ProjectService, never, never>;
+declare const generatorServicesLayer: Layer.Layer<ProjectService | ModuleTraversalService | ConfigService | SchemaService | ValidationService | MethodExtractionService | OutputService, never, never>;
 
 /** Handles aliased symbols (re-exports) */
 declare const resolveClassFromSymbol: (sym: Symbol) => Option.Option<ClassDeclaration>;
@@ -329,4 +397,4 @@ interface ModuleMetadata {
 declare const getModuleMetadata: (mod: ClassDeclaration) => ModuleMetadata;
 
 export { ConfigService, GeneratedSchemas, MethodExtractionService, MethodInfo, ModuleTraversalService, OPENAPI_MODULE_OPTIONS, OPENAPI_SPEC, OpenApiModule, OpenApiPaths$1 as OpenApiPaths, OpenApiSchema, OpenApiSpec, OutputService, ProjectService, SchemaService, SpecFileNotFoundError, SpecFileParseError, SpecFileReadError, ValidationService, filterInternalSchemas, filterInternalSchemasEffect, filterSchemas, filterSchemasEffect, generateSwaggerUiHtml, generatorServicesLayer, getArrayInitializer, getControllerName, getControllerPrefix, getControllerTags, getDecoratorName, getHttpDecorator, getHttpMethods, getModuleDecoratorArg, getModuleMetadata, getStringLiteralValue, getSymbolFromIdentifier, isHttpDecorator, isHttpMethod, isModuleClass, loadSpecFile, loadSpecFileEffect, mergeGeneratedSchemas, mergeGeneratedSchemasEffect, mergeSchemas, mergeSchemasEffect, normalizePath, normalizeSchemas, normalizeSchemasEffect, normalizeStructureRefs, normalizeStructureRefsEffect, resolveArrayOfClasses, resolveClassFromExpression, resolveClassFromSymbol, resolveOptions, toPascalCase, transformMethod, transformMethodEffect, transformMethods, transformMethodsEffect };
-export type { MergedResult, ModuleMetadata, NormalizerOptions, OpenApiModuleOptions, ResolvedOpenApiModuleOptions, SwaggerOptions };
+export type { LoadSpecFileOptions, MergedResult, ModuleMetadata, NormalizerOptions, OpenApiDocumentFileSource, OpenApiDocumentSource, OpenApiHttpApplication, OpenApiModuleOptions, OpenApiSetupOptions, ResolvedOpenApiModuleOptions, SwaggerOptions };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as OpenApiSpec, S as SpecFileNotFoundError, a as SpecFileReadError, b as SpecFileParseError, M as MethodInfo, c as OpenApiPaths, d as OpenApiOperation, e as OpenApiPaths$1, G as GeneratedSchemas, f as OpenApiSchema, g as OutputService, h as SchemaService, V as ValidationService, C as ConfigService, i as ModuleTraversalService, j as MethodExtractionService, P as ProjectService } from './shared/nestjs-openapi.NtbZNAvU.js';
-export { a4 as AnalysisError, aJ as BrokenRef, aK as BrokenRefCategories, az as ClassValidationInfo, n as Config, a3 as ConfigError, X as ConfigLoadError, W as ConfigNotFoundError, Y as ConfigValidationError, o as ContactConfig, Z as DtoGlobResolutionError, U as EntryNotFoundError, E as GenerateOptions, s as GenerateOverrides, l as GenerateResult, a5 as GeneratorError, J as HttpMethod, I as InfoConfig, _ as InvalidMethodError, am as JsonSchema, L as LicenseConfig, $ as MissingGenericSchemaTempFileCleanupError, a0 as MissingGenericSchemaTempFileWriteError, ac as ModuleWithControllers, K as OpenApiGeneratorConfig, t as OpenApiOperation, u as OpenApiParameter, v as OpenApiRequestBody, w as OpenApiResponse, q as OutputFormat, F as ParameterLocation, a8 as ProjectContext, a2 as ProjectError, Q as ProjectInitError, a9 as ProjectOptions, a6 as ProjectServiceLive, ay as PropertyValidationInfo, a1 as PublicApiError, N as ResolvedConfig, R as ResolvedParameter, H as ReturnTypeInfo, ak as SchemaError, aj as SchemaGenerationError, al as SchemaGeneratorOptions, p as ServerConfig, T as TagConfig, r as TelemetryConfig, ax as ValidationConstraints, aI as ValidationResult, au as applyConstraintsToSchema, aG as categorizeBrokenRefs, m as defineConfig, as as extractClassConstraints, aq as extractClassValidationInfo, ar as extractClassValidationInfoEffect, an as extractPropertyConstraints, ap as extractPropertyValidationInfo, aA as findConfigFile, aH as formatValidationResult, k as generate, y as generateAsync, x as generateEffect, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect, ah as generateSchemas, ai as generateSchemasFromFiles, ab as getAllControllers, af as getControllerMethodInfos, ag as getControllerMethodInfosEffect, ad as getMethodInfo, ae as getMethodInfoEffect, aa as getModules, at as getRequiredProperties, ao as isPropertyOptional, aE as loadAndResolveConfig, aC as loadConfig, aB as loadConfigFromFile, a7 as makeProjectContext, av as mergeValidationConstraints, aw as mergeValidationConstraintsEffect, aD as resolveConfig, aF as validateSpec } from './shared/nestjs-openapi.NtbZNAvU.js';
+import { O as OpenApiSpec, S as SpecFileNotFoundError, a as SpecFileReadError, b as SpecFileParseError, M as MethodInfo, c as OpenApiPaths, d as OpenApiOperation, e as OpenApiPaths$1, G as GeneratedSchemas, f as OpenApiSchema, P as ProjectService, g as ModuleTraversalService, C as ConfigService, h as SchemaService, V as ValidationService, i as MethodExtractionService, j as OutputService } from './shared/nestjs-openapi.CAanamW0.js';
+export { a4 as AnalysisError, aJ as BrokenRef, aK as BrokenRefCategories, az as ClassValidationInfo, n as Config, a3 as ConfigError, X as ConfigLoadError, W as ConfigNotFoundError, Y as ConfigValidationError, o as ContactConfig, Z as DtoGlobResolutionError, U as EntryNotFoundError, E as GenerateOptions, s as GenerateOverrides, l as GenerateResult, a5 as GeneratorError, J as HttpMethod, I as InfoConfig, _ as InvalidMethodError, am as JsonSchema, L as LicenseConfig, $ as MissingGenericSchemaTempFileCleanupError, a0 as MissingGenericSchemaTempFileWriteError, ac as ModuleWithControllers, K as OpenApiGeneratorConfig, t as OpenApiOperation, u as OpenApiParameter, v as OpenApiRequestBody, w as OpenApiResponse, q as OutputFormat, F as ParameterLocation, a8 as ProjectContext, a2 as ProjectError, Q as ProjectInitError, a9 as ProjectOptions, a6 as ProjectServiceLive, ay as PropertyValidationInfo, a1 as PublicApiError, N as ResolvedConfig, R as ResolvedParameter, H as ReturnTypeInfo, ak as SchemaError, aj as SchemaGenerationError, al as SchemaGeneratorOptions, p as ServerConfig, T as TagConfig, r as TelemetryConfig, ax as ValidationConstraints, aI as ValidationResult, au as applyConstraintsToSchema, aG as categorizeBrokenRefs, m as defineConfig, as as extractClassConstraints, aq as extractClassValidationInfo, ar as extractClassValidationInfoEffect, an as extractPropertyConstraints, ap as extractPropertyValidationInfo, aA as findConfigFile, aH as formatValidationResult, k as generate, y as generateAsync, x as generateEffect, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect, ah as generateSchemas, ai as generateSchemasFromFiles, ab as getAllControllers, af as getControllerMethodInfos, ag as getControllerMethodInfosEffect, ad as getMethodInfo, ae as getMethodInfoEffect, aa as getModules, at as getRequiredProperties, ao as isPropertyOptional, aE as loadAndResolveConfig, aC as loadConfig, aB as loadConfigFromFile, a7 as makeProjectContext, av as mergeValidationConstraints, aw as mergeValidationConstraintsEffect, aD as resolveConfig, aF as validateSpec } from './shared/nestjs-openapi.CAanamW0.js';
 import { DynamicModule } from '@nestjs/common';
 import { Effect, Option, Layer } from 'effect';
 import { ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
@@ -38,10 +38,24 @@ interface SwaggerOptions {
      */
     readonly title?: string;
 }
+interface LoadSpecFileOptions {
+    /**
+     * Additional spec files to try when the primary file is missing.
+     */
+    readonly fallbackSpecFiles?: readonly string[];
+}
+interface OpenApiDocumentFileSource extends LoadSpecFileOptions {
+    /**
+     * Path to the generated OpenAPI JSON file.
+     * Can be absolute or relative to the current working directory.
+     */
+    readonly specFile: string;
+}
+type OpenApiDocumentSource = OpenApiSpec | (() => OpenApiSpec) | OpenApiDocumentFileSource;
 /**
  * Configuration options for the OpenAPI module
  */
-interface OpenApiModuleOptions {
+interface OpenApiModuleOptions extends LoadSpecFileOptions {
     /**
      * Path to the generated OpenAPI JSON file.
      * Can be absolute or relative to the current working directory.
@@ -72,6 +86,7 @@ interface OpenApiModuleOptions {
  */
 interface ResolvedOpenApiModuleOptions {
     readonly specFile: string;
+    readonly fallbackSpecFiles: readonly string[];
     readonly enabled: boolean;
     readonly jsonPath: string;
     readonly swagger: {
@@ -88,6 +103,52 @@ declare const OPENAPI_MODULE_OPTIONS: unique symbol;
  * Injection token for the loaded OpenAPI specification
  */
 declare const OPENAPI_SPEC: unique symbol;
+interface OpenApiRouteRegistrar {
+    readonly get: (path: string, handler: (request: unknown, response: unknown) => void) => void;
+}
+interface OpenApiHttpApplication {
+    readonly config?: {
+        readonly getGlobalPrefix?: () => string;
+    };
+    readonly getHttpAdapter: () => OpenApiRouteRegistrar;
+}
+interface OpenApiSetupOptions {
+    /**
+     * Whether OpenAPI routes should be registered.
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /**
+     * Prefix OpenAPI routes with the app's `setGlobalPrefix()` value.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.useGlobalPrefix`.
+     * @default false
+     */
+    readonly useGlobalPrefix?: boolean;
+    /**
+     * Raw OpenAPI JSON endpoint path.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.jsonDocumentUrl`.
+     * @default `${docsPath}-json`
+     */
+    readonly jsonDocumentUrl?: string;
+    /**
+     * Whether Swagger UI should be served.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.ui`.
+     * @default true
+     */
+    readonly ui?: boolean;
+    /**
+     * Whether raw OpenAPI definitions should be served.
+     * Only JSON is supported.
+     * @default true
+     */
+    readonly raw?: boolean | readonly 'json'[];
+    /**
+     * Browser title for Swagger UI.
+     * Matches @nestjs/swagger's `SwaggerCustomOptions.customSiteTitle`.
+     * Uses the spec's info.title if not provided.
+     */
+    readonly customSiteTitle?: string;
+}
 /**
  * Generate Swagger UI HTML page
  */
@@ -95,8 +156,8 @@ declare function generateSwaggerUiHtml(title: string, jsonPath: string): string;
 /**
  * Load the OpenAPI spec file from disk
  */
-declare const loadSpecFileEffect: (filePath: string) => Effect.Effect<OpenApiSpec, SpecFileNotFoundError | SpecFileReadError | SpecFileParseError, never>;
-declare function loadSpecFile(filePath: string): OpenApiSpec;
+declare const loadSpecFileEffect: (filePath: string, options?: LoadSpecFileOptions | undefined) => Effect.Effect<OpenApiSpec, SpecFileNotFoundError | SpecFileReadError | SpecFileParseError, never>;
+declare function loadSpecFile(filePath: string, options?: LoadSpecFileOptions): OpenApiSpec;
 /**
  * Resolve options with defaults
  */
@@ -143,6 +204,13 @@ declare class OpenApiModule {
      * @returns Dynamic module configuration
      */
     static forRoot(options: OpenApiModuleOptions): DynamicModule;
+    /**
+     * Register OpenAPI JSON and Swagger UI routes on an already-created Nest app.
+     *
+     * Use this when the route config depends on services that are only available
+     * during bootstrap. For module-level static config, prefer `forRoot()`.
+     */
+    static setup(path: string, app: OpenApiHttpApplication, documentSource: OpenApiDocumentSource, options?: OpenApiSetupOptions): void;
 }
 
 declare const normalizePath: (path: string) => string;
@@ -159,8 +227,12 @@ declare const getHttpDecorator: (method: MethodDeclaration) => Decorator | undef
 
 declare const transformMethod: (methodInfo: MethodInfo) => OpenApiPaths;
 declare const transformMethodEffect: (methodInfo: {
-    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
+    readonly security: readonly {
+        readonly scopes: readonly string[];
+        readonly schemeName: string;
+    }[];
     readonly path: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly methodName: string;
     readonly controllerName: string;
     readonly controllerTags: readonly string[];
@@ -172,10 +244,10 @@ declare const transformMethodEffect: (methodInfo: {
     };
     readonly parameters: readonly {
         readonly name: string;
-        readonly location: "path" | "query" | "header" | "cookie" | "body";
+        readonly description: Option.Option<string>;
+        readonly location: "query" | "header" | "cookie" | "path" | "body";
         readonly tsType: string;
         readonly required: boolean;
-        readonly description: Option.Option<string>;
     }[];
     readonly decorators: readonly string[];
     readonly operation: {
@@ -185,18 +257,14 @@ declare const transformMethodEffect: (methodInfo: {
         readonly deprecated: Option.Option<boolean>;
     };
     readonly responses: readonly {
-        readonly type: Option.Option<string>;
         readonly description: Option.Option<string>;
+        readonly type: Option.Option<string>;
         readonly statusCode: number;
         readonly isArray: boolean;
     }[];
     readonly httpCode: Option.Option<number>;
     readonly consumes: readonly string[];
     readonly produces: readonly string[];
-    readonly security: readonly {
-        readonly schemeName: string;
-        readonly scopes: readonly string[];
-    }[];
 }) => Effect.Effect<OpenApiPaths, never, never>;
 type MutableOpenApiPaths = {
     [path: string]: {
@@ -205,8 +273,12 @@ type MutableOpenApiPaths = {
 };
 declare const transformMethods: (methodInfos: readonly MethodInfo[]) => OpenApiPaths;
 declare const transformMethodsEffect: (methodInfos: readonly {
-    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
+    readonly security: readonly {
+        readonly scopes: readonly string[];
+        readonly schemeName: string;
+    }[];
     readonly path: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly methodName: string;
     readonly controllerName: string;
     readonly controllerTags: readonly string[];
@@ -218,10 +290,10 @@ declare const transformMethodsEffect: (methodInfos: readonly {
     };
     readonly parameters: readonly {
         readonly name: string;
-        readonly location: "path" | "query" | "header" | "cookie" | "body";
+        readonly description: Option.Option<string>;
+        readonly location: "query" | "header" | "cookie" | "path" | "body";
         readonly tsType: string;
         readonly required: boolean;
-        readonly description: Option.Option<string>;
     }[];
     readonly decorators: readonly string[];
     readonly operation: {
@@ -231,18 +303,14 @@ declare const transformMethodsEffect: (methodInfos: readonly {
         readonly deprecated: Option.Option<boolean>;
     };
     readonly responses: readonly {
-        readonly type: Option.Option<string>;
         readonly description: Option.Option<string>;
+        readonly type: Option.Option<string>;
         readonly statusCode: number;
         readonly isArray: boolean;
     }[];
     readonly httpCode: Option.Option<number>;
     readonly consumes: readonly string[];
     readonly produces: readonly string[];
-    readonly security: readonly {
-        readonly schemeName: string;
-        readonly scopes: readonly string[];
-    }[];
 }[]) => Effect.Effect<MutableOpenApiPaths, never, never>;
 
 /**
@@ -309,7 +377,7 @@ declare const normalizeStructureRefsEffect: (schemas: GeneratedSchemas) => Effec
 /**
  * Shared service dependency graph for generation pipelines.
  */
-declare const generatorServicesLayer: Layer.Layer<OutputService | SchemaService | ValidationService | ConfigService | ModuleTraversalService | MethodExtractionService | ProjectService, never, never>;
+declare const generatorServicesLayer: Layer.Layer<ProjectService | ModuleTraversalService | ConfigService | SchemaService | ValidationService | MethodExtractionService | OutputService, never, never>;
 
 /** Handles aliased symbols (re-exports) */
 declare const resolveClassFromSymbol: (sym: Symbol) => Option.Option<ClassDeclaration>;
@@ -329,4 +397,4 @@ interface ModuleMetadata {
 declare const getModuleMetadata: (mod: ClassDeclaration) => ModuleMetadata;
 
 export { ConfigService, GeneratedSchemas, MethodExtractionService, MethodInfo, ModuleTraversalService, OPENAPI_MODULE_OPTIONS, OPENAPI_SPEC, OpenApiModule, OpenApiPaths$1 as OpenApiPaths, OpenApiSchema, OpenApiSpec, OutputService, ProjectService, SchemaService, SpecFileNotFoundError, SpecFileParseError, SpecFileReadError, ValidationService, filterInternalSchemas, filterInternalSchemasEffect, filterSchemas, filterSchemasEffect, generateSwaggerUiHtml, generatorServicesLayer, getArrayInitializer, getControllerName, getControllerPrefix, getControllerTags, getDecoratorName, getHttpDecorator, getHttpMethods, getModuleDecoratorArg, getModuleMetadata, getStringLiteralValue, getSymbolFromIdentifier, isHttpDecorator, isHttpMethod, isModuleClass, loadSpecFile, loadSpecFileEffect, mergeGeneratedSchemas, mergeGeneratedSchemasEffect, mergeSchemas, mergeSchemasEffect, normalizePath, normalizeSchemas, normalizeSchemasEffect, normalizeStructureRefs, normalizeStructureRefsEffect, resolveArrayOfClasses, resolveClassFromExpression, resolveClassFromSymbol, resolveOptions, toPascalCase, transformMethod, transformMethodEffect, transformMethods, transformMethodsEffect };
-export type { MergedResult, ModuleMetadata, NormalizerOptions, OpenApiModuleOptions, ResolvedOpenApiModuleOptions, SwaggerOptions };
+export type { LoadSpecFileOptions, MergedResult, ModuleMetadata, NormalizerOptions, OpenApiDocumentFileSource, OpenApiDocumentSource, OpenApiHttpApplication, OpenApiModuleOptions, OpenApiSetupOptions, ResolvedOpenApiModuleOptions, SwaggerOptions };