如何在NestJS Swagger中渲染不同子域名下的相同端点？

Swagger默认会合并相同路径+相同HTTP方法的端点，因为它默认不区分请求的子域名。要让不同子域名下的同路径端点都显示出来，可通过以下两种方式解决：

方法一：给端点设置唯一的operationId #

Swagger通过operationId识别唯一接口，只要保证同路径端点的operationId不同，就能避免被覆盖。

在每个控制器的接口方法上，用@ApiOperation指定不同的operationId和描述：

// 用户端登录控制器
@ApiTags('登录')
@Controller({ host: 'localhost:3000' })
export class UserLoginController {
  @Post('login')
  @ApiOperation({ 
    operationId: 'userLogin', 
    summary: '用户端登录' 
  })
  async userLogin() {
    // 业务逻辑
  }
}

// 管理端登录控制器
@ApiTags('登录')
@Controller({ host: 'admin.localhost:3000' })
export class AdminLoginController {
  @Post('login')
  @ApiOperation({ 
    operationId: 'adminLogin', 
    summary: '管理端登录' 
  })
  async adminLogin() {
    // 业务逻辑
  }
}

方法二：配置Swagger服务器并绑定控制器到对应子域名 #

通过Swagger的servers配置声明所有子域名环境，再给每个控制器绑定对应的服务器标识，让Swagger明确区分不同子域名的接口。

1. 初始化Swagger时配置全局服务器列表 #

在启动文件（如main.ts）中，设置Swagger的servers选项：

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('接口文档')
    .setDescription('多子域名接口文档')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  
  // 配置所有子域名服务器
  SwaggerModule.setup('api', app, document, {
    swaggerOptions: {
      servers: [
        { url: 'http://localhost:3000', description: '用户端环境' },
        { url: 'http://admin.localhost:3000', description: '管理端环境' },
      ],
    },
  });

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

2. 给控制器绑定对应服务器 #

在每个控制器上用@ApiServer装饰器指定所属的子域名服务器：

// 用户端登录控制器
@ApiTags('登录')
@ApiServer({ url: 'http://localhost:3000' })
@Controller({ host: 'localhost:3000' })
export class UserLoginController {
  @Post('login')
  async login() {
    // 业务逻辑
  }
}

// 管理端登录控制器
@ApiTags('登录')
@ApiServer({ url: 'http://admin.localhost:3000' })
@Controller({ host: 'admin.localhost:3000' })
export class AdminLoginController {
  @Post('login')
  async login() {
    // 业务逻辑
  }
}

配置完成后，Swagger会分别展示两个子域名下的login接口，还能通过顶部的服务器切换按钮查看对应环境的接口。

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