Configuration

All configuration is done through a TypeScript config file (typically openapi.config.ts). Use the defineConfig helper for type safety.

Config File Structure

import {  } from 'nestjs-openapi';

export default ({
  // Where to write the spec (required)
  : 'openapi.json',

  // Output format
  : 'json',

  // Input file configuration
  : {
    : 'src/app.module.ts',
  },

  // OpenAPI metadata
  : {
    : { : 'My API', : '1.0.0' },
  },

  // Generation options
  : {
    : '/api',
  },
});

`output` (required)

Path to write the generated specification. Relative to the config file.

output: 'src/openapi/spec.json';

`format`

Output format for the specification.

Value	Description
`'json'`	JSON format (default)
`'yaml'`	YAML format (fully supported)

`files`

Input file configuration. All paths are relative to the config file location.

files: {
   // Entry module file(s) - default: 'src/app.module.ts'
   entry: 'src/app.module.ts',

   // Multiple entry points (only the first is used today)
   entry: ['src/app.module.ts', 'src/admin.module.ts'],

   // tsconfig path (recommended)
   tsconfig: 'tsconfig.json',

  // Glob pattern(s) for DTO files
  dtoGlob: 'src/**/*.dto.ts',

  // Multiple DTO patterns
  dtoGlob: ['src/**/*.dto.ts', 'libs/**/*.dto.ts'],

  // Glob patterns to include
  include: ['src/**/*.ts'],

  // Glob patterns to exclude (defaults shown)
  exclude: ['**/*.spec.ts', '**/*.test.ts', '**/node_modules/**'],
}

Set tsconfig explicitly. The Promise-based generator will search upward from files.entry if omitted, but the Effect-based API requires a path.

Entry Points

The entry option specifies which module file to analyze. The library traverses @Module({ imports }) to discover all controllers.

// Single entry point
entry: 'src/app.module.ts';

// Multiple entry points (first entry is used today)
entry: ['apps/api/src/app.module.ts', 'apps/admin/src/app.module.ts'];

Multi-entry configs are normalized but the current generator only reads the first entry. Provide separate configs per app if you need multiple specs.

DTO Glob

The dtoGlob option specifies which files contain DTOs for schema generation. Only exported types are converted into schemas.

// Single pattern
dtoGlob: 'src/**/*.dto.ts';

// Multiple patterns
dtoGlob: ['src/**/*.dto.ts', 'src/**/*.entity.ts'];

Common patterns include **/*.dto.ts, **/*.entity.ts, **/*.model.ts, and **/*.schema.ts.

When a schema ref appears in paths but isn't generated from your globs, the generator tries to resolve the missing type by scanning for exported types and merges any additional schemas it finds. Keep dtoGlob focused for performance, and expand it if you still see broken ref warnings.

The CLI prints a broken refs warning if any $refs are missing. Use that list to adjust dtoGlob coverage.

`openapi`

OpenAPI specification metadata. Maps directly to the OpenAPI 3.0 spec structure.

`info` (required)

API metadata for the info section:

openapi: {
  info: {
    title: 'My API',           // required
    version: '1.0.0',          // required
    description: 'API for managing resources',
    contact: {
      name: 'API Support',
      email: 'support@example.com',
      url: 'https://support.example.com',
    },
    license: {
      name: 'MIT',
      url: 'https://opensource.org/licenses/MIT',
    },
  },
}

`servers`

Server URLs for the API:

openapi: {
  servers: [
    { url: 'https://api.example.com', description: 'Production' },
    { url: 'https://staging-api.example.com', description: 'Staging' },
    { url: 'http://localhost:3000', description: 'Development' },
  ],
}

`tags`

Tags for organizing API endpoints:

openapi: {
  tags: [
    { name: 'users', description: 'User management' },
    { name: 'posts', description: 'Blog post operations' },
    { name: 'auth', description: 'Authentication' },
  ],
}

`security`

Security schemes and global requirements. See the Security Guide for details.

openapi: {
  security: {
    schemes: [
      {
        name: 'bearerAuth',
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    ],
    global: [{ bearerAuth: [] }],
  },
}

`options`

Generation behavior options.

`basePath`

Global prefix for all routes. Equivalent to NestJS's app.setGlobalPrefix():

options: {
  basePath: '/api/v1',
}

With this configuration, a route GET /users becomes GET /api/v1/users.

`extractValidation`

Extract validation constraints from class-validator decorators (default: true):

options: {
  extractValidation: true,
}

See the Validation Guide for details.

`excludeDecorators`

Decorator names that exclude endpoints from the spec:

options: {
  // Default values
  excludeDecorators: ['ApiExcludeEndpoint', 'ApiExcludeController'],

  // Add custom decorators
  excludeDecorators: ['ApiExcludeEndpoint', 'Internal', 'AdminOnly'],
}

`pathFilter`

Filter paths by regex or predicate function. Paths matching the regex (or returning true) are included:

options: {
  // Exclude paths containing '/internal/'
  pathFilter: /^(?!.*\/internal\/).*/,

  // Using a function
  pathFilter: (path) => !path.includes('/internal/'),

  // Include only v2 API paths
  pathFilter: /^\/api\/v2\//,
}

`query`

Query parameter handling options.

`query.style`

Controls how query DTOs are represented in the spec (default: "inline").

Value	Description
`"inline"`	Expand DTO properties as individual query parameters (default)
`"ref"`	Keep as a single parameter with a schema reference

By default, when @Query() is used without an explicit parameter name (e.g., @Query() pagination: PaginationDto), the DTO properties are inlined as individual query parameters. This is the standard OpenAPI practice and works better with code generators and API clients.

// Controller:
@Get()
findAll(@Query() pagination: PaginationDto) { ... }

// Default output (style: "inline"):
// parameters:
//   - name: page
//     in: query
//     required: false
//   - name: limit
//     in: query
//     required: false

Set query.style: "ref" to keep query DTOs as schema references:

options: {
  query: { style: 'ref' },
}

// Output with style: "ref":
// parameters:
//   - name: pagination
//     in: query
//     schema:
//       $ref: '#/components/schemas/PaginationDto'

Explicit named params like @Query('filter') filter: FilterDto are never inlined—they always use a schema reference regardless of this setting.

`extends`

The type definition includes an extends field for future shared configs, but it is not implemented in the current Promise-based generator. Keep configs standalone for now.

Complete Example

import {  } from 'nestjs-openapi';

export default ({
  : 'src/openapi/openapi.generated.json',
  : 'json',

  : {
    : 'src/app.module.ts',
    : 'tsconfig.json',
    : 'src/**/*.dto.ts',
    : ['**/*.spec.ts', '**/*.test.ts'],
  },

  : {
    : {
      : 'Todo API',
      : '1.0.0',
      : 'A simple todo management API',
      : {
        : 'API Support',
        : 'support@example.com',
      },
      : {
        : 'MIT',
      },
    },
    : [
      { : 'https://api.todo.example.com', : 'Production' },
      { : 'http://localhost:3000', : 'Development' },
    ],
    : [
      { : 'todos', : 'Todo operations' },
      { : 'users', : 'User management' },
    ],
    : {
      : [
        {
          : 'bearerAuth',
          : 'http',
          : 'bearer',
          : 'JWT',
        },
      ],
      : [{ : [] }],
    },
  },

  : {
    : '/api/v1',
    : true,
    : ['ApiExcludeEndpoint', 'Internal'],
    : /^(?!.*\/internal\/).*/,
  },
});

Next Steps

Decorators Guide - Supported NestJS and Swagger decorators
Security Guide - Configure authentication schemes
Validation Guide - Extract class-validator constraints

On this page