NestJS — Enterprise Node.js

OpenAPI Advanced: Types, Operations, Security & CLI Plugin

18 min Lesson 72 of 80

OpenAPI Advanced: Types, Operations, Security & CLI Plugin

Swagger documentation becomes valuable when it accurately describes inputs, responses, authentication, and error cases. NestJS OpenAPI decorators and the CLI plugin help keep generated docs close to the code.

Core idea

This feature is about controlling how the application is organized and how it behaves at runtime. These are the points a developer should understand before using it in a real project:

ApiProperty describes DTO fields that TypeScript reflection cannot fully infer, such as arrays, enums, examples, and nullable fields.
ApiOperation, ApiResponse, and ApiTags make generated docs navigable and useful to clients.
ApiBearerAuth and security schemes document how protected endpoints authenticate.
OpenAPI mapped types derive update and partial DTOs consistently.
The Swagger CLI plugin can reduce repetitive ApiProperty decorators, but generated output still needs review.

Practical example

The following example shows the idea in a practical NestJS project. The goal is not to memorize the snippet, but to understand where it belongs in the architecture:

@ApiTags('orders')
@ApiBearerAuth()
@Controller('orders')
export class OrdersController {
  @Post()
  @ApiOperation({ summary: 'Create an order' })
  @ApiCreatedResponse({ type: OrderResponseDto })
  @ApiBadRequestResponse({ description: 'Validation failed' })
  create(@Body() dto: CreateOrderDto) {
    return this.ordersService.create(dto);
  }
}

Design note: Good OpenAPI docs are a contract. They should be good enough for another developer to integrate without reading your controller source.

Production checklist

Document success and common error responses.
Add auth schemes and apply them to protected operations.
Use examples for tricky DTO fields.
Regenerate and review docs after DTO or route changes.

Rule of thumb: If the feature makes boundaries clearer and tests easier, it is probably the right choice. If it hides dependencies or makes tracing harder, redesign.

Summary

This lesson covers an advanced NestJS area that matters when building enterprise applications. Focus on clear boundaries, testable behavior, and choosing the right tool for the context instead of using every feature everywhere.