nestjs-openapi 0.2.2 → 0.3.1

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.CU_zMKfF.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, g as SchemaService, h as OutputService, C as ConfigService, i as ModuleTraversalService, j as MethodExtractionService, V as ValidationService, P as ProjectService } from './shared/nestjs-openapi.CDtSgIYg.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.CDtSgIYg.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,10 +227,10 @@ 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 path: string;
-    readonly methodName: string;
     readonly controllerName: string;
+    readonly methodName: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly controllerTags: readonly string[];
     readonly returnType: {
         readonly filePath: Option.Option<string>;
@@ -185,8 +253,8 @@ 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;
     }[];
@@ -205,10 +273,10 @@ 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 path: string;
-    readonly methodName: string;
     readonly controllerName: string;
+    readonly methodName: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly controllerTags: readonly string[];
     readonly returnType: {
         readonly filePath: Option.Option<string>;
@@ -231,8 +299,8 @@ 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;
     }[];
@@ -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<SchemaService | OutputService | ConfigService | ModuleTraversalService | MethodExtractionService | ValidationService | ProjectService, 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, g as SchemaService, h as OutputService, C as ConfigService, i as ModuleTraversalService, j as MethodExtractionService, V as ValidationService, P as ProjectService } from './shared/nestjs-openapi.CDtSgIYg.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.CDtSgIYg.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,10 +227,10 @@ 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 path: string;
-    readonly methodName: string;
     readonly controllerName: string;
+    readonly methodName: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly controllerTags: readonly string[];
     readonly returnType: {
         readonly filePath: Option.Option<string>;
@@ -185,8 +253,8 @@ 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;
     }[];
@@ -205,10 +273,10 @@ 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 path: string;
-    readonly methodName: string;
     readonly controllerName: string;
+    readonly methodName: string;
+    readonly httpMethod: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "ALL";
     readonly controllerTags: readonly string[];
     readonly returnType: {
         readonly filePath: Option.Option<string>;
@@ -231,8 +299,8 @@ 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;
     }[];
@@ -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<SchemaService | OutputService | ConfigService | ModuleTraversalService | MethodExtractionService | ValidationService | ProjectService, 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.mjs

@@ -1,10 +1,10 @@
-import { S as SpecFileNotFoundError, a as SpecFileReadError, b as SpecFileParseError } from './shared/nestjs-openapi.DeikubMm.mjs';
-export { c as ConfigLoadError, C as ConfigNotFoundError, ae as ConfigService, e as ConfigValidationError, D as DtoGlobResolutionError, E as EntryNotFoundError, I as InvalidMethodError, B as MethodExtractionService, M as MissingGenericSchemaTempFileCleanupError, f as MissingGenericSchemaTempFileWriteError, n as ModuleTraversalService, ad as OutputService, P as ProjectInitError, i as ProjectService, j as ProjectServiceLive, h as PublicApiError, a0 as SchemaGenerationError, a1 as SchemaService, ac as ValidationService, a9 as applyConstraintsToSchema, av as categorizeBrokenRefs, d as defineConfig, a7 as extractClassConstraints, a5 as extractClassValidationInfo, a6 as extractClassValidationInfoEffect, a2 as extractPropertyConstraints, a4 as extractPropertyValidationInfo, V as filterInternalSchemas, W as filterInternalSchemasEffect, Q as filterSchemas, R as filterSchemasEffect, af as findConfigFile, aw as formatValidationResult, g as generate, _ as generateSchemas, $ as generateSchemasFromFiles, ak as generatorServicesLayer, l as getAllControllers, am as getArrayInitializer, z as getControllerMethodInfos, A as getControllerMethodInfosEffect, p as getControllerName, o as getControllerPrefix, t as getControllerTags, s as getDecoratorName, u as getHttpDecorator, r as getHttpMethods, x as getMethodInfo, y as getMethodInfoEffect, aq as getModuleDecoratorArg, at as getModuleMetadata, k as getModules, a8 as getRequiredProperties, an as getStringLiteralValue, ao as getSymbolFromIdentifier, v as isHttpDecorator, q as isHttpMethod, ap as isModuleClass, a3 as isPropertyOptional, aj as loadAndResolveConfig, ah as loadConfig, ag as loadConfigFromFile, m as makeProjectContext, N as mergeGeneratedSchemas, O as mergeGeneratedSchemasEffect, K as mergeSchemas, L as mergeSchemasEffect, aa as mergeValidationConstraints, ab as mergeValidationConstraintsEffect, w as normalizePath, T as normalizeSchemas, U as normalizeSchemasEffect, X as normalizeStructureRefs, Y as normalizeStructureRefsEffect, as as resolveArrayOfClasses, ar as resolveClassFromExpression, al as resolveClassFromSymbol, ai as resolveConfig, Z as toPascalCase, F as transformMethod, G as transformMethodEffect, H as transformMethods, J as transformMethodsEffect, au as validateSpec } from './shared/nestjs-openapi.DeikubMm.mjs';
+import { S as SpecFileNotFoundError, a as SpecFileParseError, b as SpecFileReadError } from './shared/nestjs-openapi.CU_zMKfF.mjs';
+export { c as ConfigLoadError, C as ConfigNotFoundError, ae as ConfigService, e as ConfigValidationError, D as DtoGlobResolutionError, E as EntryNotFoundError, I as InvalidMethodError, B as MethodExtractionService, M as MissingGenericSchemaTempFileCleanupError, f as MissingGenericSchemaTempFileWriteError, n as ModuleTraversalService, ad as OutputService, P as ProjectInitError, i as ProjectService, j as ProjectServiceLive, h as PublicApiError, a0 as SchemaGenerationError, a1 as SchemaService, ac as ValidationService, a9 as applyConstraintsToSchema, av as categorizeBrokenRefs, d as defineConfig, a7 as extractClassConstraints, a5 as extractClassValidationInfo, a6 as extractClassValidationInfoEffect, a2 as extractPropertyConstraints, a4 as extractPropertyValidationInfo, V as filterInternalSchemas, W as filterInternalSchemasEffect, Q as filterSchemas, R as filterSchemasEffect, af as findConfigFile, aw as formatValidationResult, g as generate, _ as generateSchemas, $ as generateSchemasFromFiles, ak as generatorServicesLayer, l as getAllControllers, am as getArrayInitializer, z as getControllerMethodInfos, A as getControllerMethodInfosEffect, p as getControllerName, o as getControllerPrefix, t as getControllerTags, s as getDecoratorName, u as getHttpDecorator, r as getHttpMethods, x as getMethodInfo, y as getMethodInfoEffect, aq as getModuleDecoratorArg, at as getModuleMetadata, k as getModules, a8 as getRequiredProperties, an as getStringLiteralValue, ao as getSymbolFromIdentifier, v as isHttpDecorator, q as isHttpMethod, ap as isModuleClass, a3 as isPropertyOptional, aj as loadAndResolveConfig, ah as loadConfig, ag as loadConfigFromFile, m as makeProjectContext, N as mergeGeneratedSchemas, O as mergeGeneratedSchemasEffect, K as mergeSchemas, L as mergeSchemasEffect, aa as mergeValidationConstraints, ab as mergeValidationConstraintsEffect, w as normalizePath, T as normalizeSchemas, U as normalizeSchemasEffect, X as normalizeStructureRefs, Y as normalizeStructureRefsEffect, as as resolveArrayOfClasses, ar as resolveClassFromExpression, al as resolveClassFromSymbol, ai as resolveConfig, Z as toPascalCase, F as transformMethod, G as transformMethodEffect, H as transformMethods, J as transformMethodsEffect, au as validateSpec } from './shared/nestjs-openapi.CU_zMKfF.mjs';
 import { readFileSync } from 'node:fs';
 import { fail } from 'node:assert';
 import { resolve } from 'node:path';
 import { Module } from '@nestjs/common';
-import { Effect, Exit, Cause, Option } from 'effect';
+import { Effect, Either, Exit, Cause, Option } from 'effect';
 export { generateAsync, generate as generateEffect, generateFromConfigAsync, generateFromConfigEffect, generatePathsAsync, generatePathsEffect } from './internal.mjs';
 import 'node:crypto';
 import 'ts-morph';
@@ -94,21 +94,40 @@ function generateSwaggerUiHtml(title, jsonPath) {
 </body>
 </html>`;
 }
+function isErrorWithCode(cause, code) {
+  return cause !== null && typeof cause === "object" && "code" in cause && cause.code === code;
+}
+function getSpecFileCandidates(filePath, options = {}) {
+  const candidates = [filePath];
+  candidates.push(...options.fallbackSpecFiles ?? []);
+  return [...new Set(candidates)];
+}
+const readSpecFileContentEffect = (filePath) => Effect.try({
+  try: () => readFileSync(resolve(process.cwd(), filePath), "utf-8"),
+  catch: (cause) => isErrorWithCode(cause, "ENOENT") ? SpecFileNotFoundError.create(filePath) : SpecFileReadError.create(filePath, cause)
+});
 const loadSpecFileEffect = Effect.fn("OpenApiModule.loadSpecFile")(
-  function* (filePath) {
-    const resolvedPath = resolve(process.cwd(), filePath);
-    const content = yield* Effect.try({
-      try: () => readFileSync(resolvedPath, "utf-8"),
-      catch: (cause) => cause && typeof cause === "object" && "code" in cause && cause.code === "ENOENT" ? SpecFileNotFoundError.create(filePath) : SpecFileReadError.create(filePath, cause)
-    });
-    return yield* Effect.try({
-      try: () => JSON.parse(content),
-      catch: (cause) => SpecFileParseError.create(filePath, cause)
-    });
+  function* (filePath, options = {}) {
+    for (const candidate of getSpecFileCandidates(filePath, options)) {
+      const contentResult = yield* readSpecFileContentEffect(candidate).pipe(
+        Effect.either
+      );
+      if (Either.isLeft(contentResult)) {
+        if (contentResult.left instanceof SpecFileNotFoundError) {
+          continue;
+        }
+        return yield* Effect.fail(contentResult.left);
+      }
+      return yield* Effect.try({
+        try: () => JSON.parse(contentResult.right),
+        catch: (cause) => SpecFileParseError.create(candidate, cause)
+      });
+    }
+    return yield* Effect.fail(SpecFileNotFoundError.create(filePath));
   }
 );
-function loadSpecFile(filePath) {
-  const exit = Effect.runSyncExit(loadSpecFileEffect(filePath));
+function loadSpecFile(filePath, options = {}) {
+  const exit = Effect.runSyncExit(loadSpecFileEffect(filePath, options));
   if (Exit.isSuccess(exit)) {
     return exit.value;
   }
@@ -131,6 +150,7 @@ function resolveOptions(options) {
   }
   return {
     specFile: options.specFile,
+    fallbackSpecFiles: options.fallbackSpecFiles ?? [],
     enabled: options.enabled ?? true,
     jsonPath: options.jsonPath ?? "/openapi.json",
     swagger: {
@@ -140,6 +160,26 @@ function resolveOptions(options) {
     }
   };
 }
+function resolveOptionsWithSpecTitle(options, spec) {
+  return {
+    ...options,
+    swagger: {
+      ...options.swagger,
+      title: options.swagger.title || spec.info.title
+    }
+  };
+}
+function createOpenApiModuleState(options) {
+  const resolvedOptions = resolveOptions(options);
+  if (!resolvedOptions.enabled) {
+    return { options: resolvedOptions };
+  }
+  const spec = loadSpecFile(resolvedOptions.specFile, resolvedOptions);
+  return {
+    spec,
+    options: resolveOptionsWithSpecTitle(resolvedOptions, spec)
+  };
+}
 _OpenApiModule_decorators = [Module({})];
 let _OpenApiModule = class _OpenApiModule {
   /**
@@ -149,8 +189,8 @@ let _OpenApiModule = class _OpenApiModule {
    * @returns Dynamic module configuration
    */
   static forRoot(options) {
-    const resolvedOptions = resolveOptions(options);
-    if (!resolvedOptions.enabled) {
+    const state = createOpenApiModuleState(options);
+    if (!state.options.enabled || !state.spec) {
       return {
         module: _OpenApiModule,
         providers: [],
@@ -158,25 +198,17 @@ let _OpenApiModule = class _OpenApiModule {
         exports: []
       };
     }
-    const spec = loadSpecFile(resolvedOptions.specFile);
-    const finalOptions = {
-      ...resolvedOptions,
-      swagger: {
-        ...resolvedOptions.swagger,
-        title: resolvedOptions.swagger.title || spec.info.title
-      }
-    };
     const providers = [
       {
         provide: OPENAPI_MODULE_OPTIONS,
-        useValue: finalOptions
+        useValue: state.options
       },
       {
         provide: OPENAPI_SPEC,
-        useValue: spec
+        useValue: state.spec
       }
     ];
-    const controllers = createOpenApiControllers(finalOptions, spec);
+    const controllers = createOpenApiControllers(state.options, state.spec);
     return {
       module: _OpenApiModule,
       providers,
@@ -184,11 +216,97 @@ let _OpenApiModule = class _OpenApiModule {
       exports: [OPENAPI_MODULE_OPTIONS, OPENAPI_SPEC]
     };
   }
+  /**
+   * 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, app, documentSource, options = {}) {
+    if (options.enabled === false) {
+      return;
+    }
+    const spec = loadDocumentSource(documentSource);
+    const httpAdapter = app.getHttpAdapter();
+    const swaggerPath = resolveSetupPath(path, app, options);
+    const jsonPath = resolveJsonDocumentUrl(swaggerPath, app, options);
+    if (shouldServeJson(options.raw)) {
+      httpAdapter.get(jsonPath, (_request, response) => {
+        sendResponse(response, spec, "application/json");
+      });
+    }
+    if (options.ui !== false) {
+      httpAdapter.get(swaggerPath, (_request, response) => {
+        sendResponse(
+          response,
+          generateSwaggerUiHtml(
+            options.customSiteTitle ?? spec.info.title,
+            jsonPath
+          ),
+          "text/html"
+        );
+      });
+    }
+  }
 };
 _init = __decoratorStart();
 _OpenApiModule = __decorateElement(_init, 0, "OpenApiModule", _OpenApiModule_decorators, _OpenApiModule);
 __runInitializers(_init, 1, _OpenApiModule);
 let OpenApiModule = _OpenApiModule;
+function loadDocumentSource(source) {
+  if (typeof source === "function") {
+    return source();
+  }
+  if (isDocumentFileSource(source)) {
+    return loadSpecFile(source.specFile, source);
+  }
+  return source;
+}
+function isDocumentFileSource(source) {
+  return source !== null && typeof source === "object" && "specFile" in source && typeof source.specFile === "string";
+}
+function resolveSetupPath(path, app, options) {
+  return joinRoutePath(
+    options.useGlobalPrefix === true ? getGlobalPrefix(app) : void 0,
+    path
+  );
+}
+function resolveJsonDocumentUrl(finalSwaggerPath, app, options) {
+  if (!options.jsonDocumentUrl) {
+    return `${finalSwaggerPath}-json`;
+  }
+  return joinRoutePath(
+    options.useGlobalPrefix === true ? getGlobalPrefix(app) : void 0,
+    options.jsonDocumentUrl
+  );
+}
+function getGlobalPrefix(app) {
+  const appWithConfig = app;
+  return appWithConfig.config?.getGlobalPrefix?.() ?? "";
+}
+function shouldServeJson(raw) {
+  return raw === void 0 || raw === true || Array.isArray(raw) && raw.length > 0;
+}
+function joinRoutePath(...parts) {
+  return `/${parts.filter((part) => part !== void 0 && part !== "").map((part) => part.replace(/^\/+|\/+$/g, "")).filter((part) => part.length > 0).join("/")}`;
+}
+function sendResponse(response, body, contentType) {
+  const responseLike = response;
+  responseLike.setHeader?.("Content-Type", contentType);
+  if (contentType === "application/json" && responseLike.json) {
+    responseLike.json(body);
+    return;
+  }
+  if (responseLike.type && responseLike.send) {
+    responseLike.type(contentType).send(body);
+    return;
+  }
+  if (responseLike.send) {
+    responseLike.send(body);
+    return;
+  }
+  responseLike.end?.(typeof body === "string" ? body : JSON.stringify(body));
+}
 function createJsonController(controllerPath, spec) {
   class JsonSpecController {
     getSpec() {

package/dist/internal.d.mts

@@ -1,3 +1,3 @@
-export { E as GenerateOptions, x as generate, y as generateAsync, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect } from './shared/nestjs-openapi.NtbZNAvU.mjs';
+export { E as GenerateOptions, x as generate, y as generateAsync, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect } from './shared/nestjs-openapi.CDtSgIYg.mjs';
 import 'effect';
 import 'ts-morph';

package/dist/internal.d.ts

@@ -1,3 +1,3 @@
-export { E as GenerateOptions, x as generate, y as generateAsync, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect } from './shared/nestjs-openapi.NtbZNAvU.js';
+export { E as GenerateOptions, x as generate, y as generateAsync, D as generateFromConfigAsync, B as generateFromConfigEffect, A as generatePathsAsync, z as generatePathsEffect } from './shared/nestjs-openapi.CDtSgIYg.js';
 import 'effect';
 import 'ts-morph';

package/dist/internal.mjs

@@ -1,5 +1,5 @@
 import { Effect } from 'effect';
-import { i as ProjectService, n as ModuleTraversalService, B as MethodExtractionService, J as transformMethodsEffect, ax as generateEffect, ay as runProjectApiPromise, ak as generatorServicesLayer, az as runtimeLayerFor, aA as runGeneratorApiPromise } from './shared/nestjs-openapi.DeikubMm.mjs';
+import { i as ProjectService, n as ModuleTraversalService, B as MethodExtractionService, J as transformMethodsEffect, ax as generateEffect, ay as runProjectApiPromise, ak as generatorServicesLayer, az as runtimeLayerFor, aA as runGeneratorApiPromise } from './shared/nestjs-openapi.CU_zMKfF.mjs';
 import 'node:fs';
 import 'node:path';
 import 'node:crypto';