如何在Nest JS框架中解耦Swagger代码与业务代码

Hey there! I totally get your frustration about Swagger code coupling with business logic and lingering in production builds. Let’s walk through practical, clean ways to fix this:

1. Conditionally Initialize Swagger Based on Environment #

The easiest first step is to only fire up Swagger when you’re in development or testing environments.

First, extract your Swagger setup logic into a separate utility function to keep your main file tidy:

// src/utils/swagger.setup.ts
import { INestApplication } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

export function setupSwagger(app: INestApplication) {
  const docConfig = new DocumentBuilder()
    .setTitle('Your API')
    .setDescription('Full API documentation')
    .setVersion('1.0')
    .build();
  const apiDocument = SwaggerModule.createDocument(app, docConfig);
  SwaggerModule.setup('api-docs', app, apiDocument);
}

Then, in your main.ts, check the environment before running this setup:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { setupSwagger } from './utils/swagger.setup';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // Only enable Swagger in non-production environments
  if (process.env.NODE_ENV !== 'production') {
    setupSwagger(app);
  }

  await app.listen(3000);
}
bootstrap();

Modern bundlers like Webpack (used by NestJS) will tree-shake unused Swagger code in production if the environment check is statically analyzable.

2. Wrap Swagger Decorators in Environment-Aware Custom Decorators #

To decouple Swagger’s decorators from your business controllers, create custom decorators that act as no-ops in production.

Make a dedicated file for these custom decorators:

// src/decorators/api.decorators.ts
import { ApiOperation as SwaggerApiOp, ApiResponse as SwaggerApiRes } from '@nestjs/swagger';

// Empty decorator that does nothing in production
const noopDecorator = () => () => {};

export const ApiOperation = process.env.NODE_ENV === 'production' 
  ? noopDecorator 
  : SwaggerApiOp;

export const ApiResponse = process.env.NODE_ENV === 'production' 
  ? noopDecorator 
  : SwaggerApiRes;

Now use these custom decorators in your controllers instead of direct Swagger imports:

import { Controller, Get } from '@nestjs/common';
import { ApiOperation, ApiResponse } from '../decorators/api.decorators';

@Controller('products')
export class ProductsController {
  @Get()
  @ApiOperation({ summary: 'Fetch all products' })
  @ApiResponse({ status: 200, description: 'List of products' })
  getAllProducts() {
    // Your business logic here
  }
}

In production, these decorators won’t add any Swagger-related code to your controllers.

3. Use a Feature Module for Swagger (Conditional Import) #

If you prefer modular organization, create a dedicated Swagger module and only import it in non-production environments.

First, build the Swagger feature module:

// src/swagger/swagger.module.ts
import { Module } from '@nestjs/common';
import { SwaggerModule } from '@nestjs/swagger';

@Module({
  imports: [SwaggerModule],
})
export class SwaggerFeatureModule {}

Then, conditionally import it in your AppModule:

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { SwaggerFeatureModule } from './swagger/swagger.module';

@Module({
  imports: [
    ConfigModule.forRoot(),
    // Only load Swagger module in non-production
    ...(process.env.NODE_ENV !== 'production' ? [SwaggerFeatureModule] : []),
  ],
})
export class AppModule {}

This keeps Swagger’s entire module out of your production build entirely.

A Quick Note on Performance #

As @j_steenkamp_twitter mentioned, Swagger’s runtime footprint is actually quite small and shouldn’t cause any noticeable performance hits in production. But if you want to eliminate it completely for peace of mind, the methods above will help you fully decouple Swagger from your production codebase.

内容的提问来源于stack exchange，提问作者soundar pandiyan