OpenApiModule

A NestJS dynamic module for serving generated OpenAPI specifications at runtime. Optionally serves Swagger UI for interactive documentation.

Import

import { OpenApiModule } from 'nestjs-openapi';

forRoot()

Configure and register the module.

Signature

class OpenApiModule {
  static forRoot(options: OpenApiModuleOptions): DynamicModule;
}

Parameters

Parameter	Type	Description
`options`	`OpenApiModuleOptions`	Module configuration

OpenApiModuleOptions

interface OpenApiModuleOptions {
  /**
   * Path to the generated OpenAPI JSON file.
   * Can be absolute or relative to process.cwd().
   * @required
   */
  readonly specFile: string;

  /**
   * Whether the module is enabled.
   * When false, no routes are registered.
   * @default true
   */
  readonly enabled?: boolean;

  /**
   * 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;
}

interface SwaggerOptions {
  /**
   * Path where Swagger UI will be served.
   * @default "/api-docs"
   */
  readonly path?: string;

  /**
   * Custom title for the Swagger UI page.
   * Uses spec's info.title if not provided.
   */
  readonly title?: string;
}

Returns

DynamicModule - NestJS dynamic module configuration.

Example

Basic Usage

import { Module } from '@nestjs/common';
import { OpenApiModule } from 'nestjs-openapi';

@Module({
  imports: [
    OpenApiModule.forRoot({
      specFile: 'openapi.json',
    }),
  ],
})
export class AppModule {}

Serves the spec at GET /openapi.json.

With Swagger UI (Simple)

@Module({
  imports: [
    OpenApiModule.forRoot({
      specFile: 'openapi.json',
      swagger: true,
    }),
  ],
})
export class AppModule {}

Creates two endpoints:

GET /openapi.json - Raw OpenAPI specification
GET /api-docs - Swagger UI interface

With Swagger UI (Custom)

@Module({
  imports: [
    OpenApiModule.forRoot({
      specFile: 'openapi.json',
      swagger: {
        path: '/docs',
        title: 'My API Documentation',
      },
    }),
  ],
})
export class AppModule {}

Environment-Based

@Module({
  imports: [
    OpenApiModule.forRoot({
      specFile: 'openapi.json',
      enabled: process.env.NODE_ENV !== 'production',
      swagger: process.env.SWAGGER_UI === 'true',
    }),
  ],
})
export class AppModule {}

Custom Paths

@Module({
  imports: [
    OpenApiModule.forRoot({
      specFile: 'openapi.json',
      jsonPath: '/api/v1/openapi.json',
      swagger: {
        path: '/api/v1/docs',
        title: 'My API v1 Documentation',
      },
    }),
  ],
})
export class AppModule {}

Injection Tokens

The module exports two injection tokens for accessing the spec and options in your services.

OPENAPI_SPEC

Inject the loaded OpenAPI specification:

import { Injectable, Inject } from '@nestjs/common';
import { OPENAPI_SPEC } from 'nestjs-openapi';
import type { OpenApiSpec } from 'nestjs-openapi';

@Injectable()
export class ApiInfoService {
  constructor(@Inject(OPENAPI_SPEC) private readonly spec: OpenApiSpec) {}

  getVersion(): string {
    return this.spec.info.version;
  }

  getEndpoints(): string[] {
    return Object.keys(this.spec.paths);
  }

  getOperationCount(): number {
    return Object.values(this.spec.paths).flatMap((methods) =>
      Object.keys(methods),
    ).length;
  }
}

OPENAPI_MODULE_OPTIONS

Inject the resolved module options:

import { Injectable, Inject } from '@nestjs/common';
import { OPENAPI_MODULE_OPTIONS } from 'nestjs-openapi';
import type { ResolvedOpenApiModuleOptions } from 'nestjs-openapi';

@Injectable()
export class DocsService {
  constructor(
    @Inject(OPENAPI_MODULE_OPTIONS)
    private readonly options: ResolvedOpenApiModuleOptions,
  ) {}

  getDocsUrl(): string {
    return this.options.swagger.enabled
      ? this.options.swagger.path
      : this.options.jsonPath;
  }
}

Helper Functions

loadSpecFile()

Load an OpenAPI spec file from disk:

import { loadSpecFile } from 'nestjs-openapi';

const spec = loadSpecFile('openapi.json');
console.log(spec.info.title);

Throws an error if the file is not found.

generateSwaggerUiHtml()

Generate the Swagger UI HTML page:

import { generateSwaggerUiHtml } from 'nestjs-openapi';

const html = generateSwaggerUiHtml('My API', '/openapi.json');
// Returns full HTML page with Swagger UI

resolveOptions()

Resolve options with defaults:

import { resolveOptions } from 'nestjs-openapi';

const options = resolveOptions({
  specFile: 'openapi.json',
});

console.log(options.jsonPath); // '/openapi.json'
console.log(options.enabled); // true
console.log(options.swagger.enabled); // false

ResolvedOpenApiModuleOptions

The resolved options interface 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;
  };
}

Error Handling

If the spec file is not found when the module initializes:

Error: OpenAPI spec file not found: openapi.json.
Make sure to run 'nestjs-openapi generate' first.

Ensure you run nestjs-openapi generate before starting your application.

Disabled Module

When enabled: false, the module returns an empty configuration:

OpenApiModule.forRoot({
  specFile: 'openapi.json',
  enabled: false, // No routes registered
});

This is useful for conditionally disabling OpenAPI in production:

enabled: process.env.NODE_ENV !== 'production';