Skip to content
LiveNew tools this week
Submit
AIMarketly
NestJS OpenAPI logo

NestJS OpenAPI

Swagger automation and Generic response documentation.

ngxtm/devkit0installs8starsSecurity

SKILL.md

Full skill instructions

OpenAPI & Documentation

Swagger (OpenAPI)

  • Automation: ALWAYS use the Nest CLI Plugin (@nestjs/​swagger/​plugin).
    • Benefit: Auto-generates @ApiProperty for DTOs and response types. Reduces boilerplate by 50%.
    • Config: nest-cli.json -> "plugins": ["@nestjs/​swagger"].
  • Versioning: Maintain separate Swagger docs for v1, v2 if breaking changes occur.

Response Documentation

  • Strictness: Every controller method must have @ApiResponse({ status: 200, type: UserDto }).
  • Generic Wrappers: Define ApiPaginatedResponse<T> decorators to document generic PageDto<T> returns properly (Swagger doesn't handle generics well by default).
    • Technique: Use ApiExtraModels + getSchemaPath() in the custom decorator to handle the generic T ref.

Advanced Patterns

  • Polymorphism: Use @ApiExtraModels and getSchemaPath for oneOf/anyOf union types.
  • File Uploads: Document multipart/​form-data explicitly.
    • Decorator: @ApiConsumes('multipart/​form-data').
    • Body: @ApiBody({ schema: { type: 'object', properties: { file: { type: 'string', format: 'binary' } } } }).
  • Authentication: Specify granular security schemes per route/​controller.
    • Types: @ApiBearerAuth() or @ApiSecurity('api-key') (Must match DocumentBuilder().addBearerAuth()).
  • Enums: Force named enums for reusable schema references.
    • Code: @ApiProperty({ enum: MyEnum, enumName: 'MyEnum' }).

Operation Grouping

  • Tags: Mandatory @ApiTags('domains') on every Controller to group endpoints logically.

  • Multiple Docs: generate separate docs for different audiences (e.g. Public vs Internal).

    SwaggerModule.createDocument(app, config, { include: [PublicModule] }); // /​api/​docs
SwaggerModule.createDocument(app, adminConfig, { include: [AdminModule] }); // /​admin/​docs

Self-Documentation

  • Compodoc: Use @compodoc/​compodoc to generate static documentation of the module graph, services, and dependencies.
    • Use Case: New developer onboarding and architectural review.

Advanced OpenAPI

  • Polymorphism: Use @ApiExtraModels and getSchemaPath for oneOf/anyOf union types.
    • Pattern: Register generic/​sub-types in controller, refer via schema $ref.
  • File Uploads: Document multipart/​form-data explicitly.
    • Decorator: @ApiConsumes('multipart/​form-data').
    • Body: @ApiBody({ schema: { type: 'object', properties: { file: { type: 'string', format: 'binary' } } } }).
  • Authentication: Specify granular security schemes per route/​controller.
    • Types: @ApiBearerAuth() or @ApiSecurity('api-key'). Match setup in DocumentBuilder.
  • Enums: Force named enums for reusable schema references.
    • Code: @ApiProperty({ enum: MyEnum, enumName: 'MyEnum' }).
  • Grouping: Segregate public vs. internal docs.
    • Setup: SwaggerModule.createDocument(app, config, { include: [AdminModule] }).