如何在Node.js应用中对Swagger接口（Endpoints）进行分组？

如果你的Node.js项目里Swagger接口一直停留在默认分组，试了多种方法都没实现简洁的分组效果，下面是经过验证的解决方式：

基于 swagger-jsdoc + swagger-ui-express 的分组配置 #

这是Express生态下最常用的组合，核心是为不同分组定义独立的Swagger规范，再挂载到不同路由：

1. 定义多组Swagger配置对象

// V1 版本API配置
const swaggerV1Options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'V1 API 文档',
      version: '1.0.0',
      description: 'V1版本的业务接口集合'
    },
    servers: [{ url: '/api/v1' }]
  },
  apis: ['./src/routes/v1/**/*.js'] // 仅扫描V1目录下的接口注释
};

// V2 版本API配置
const swaggerV2Options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'V2 API 文档',
      version: '2.0.0',
      description: 'V2版本的业务接口集合'
    },
    servers: [{ url: '/api/v2' }]
  },
  apis: ['./src/routes/v2/**/*.js'] // 仅扫描V2目录下的接口注释
};

2. 生成文档并挂载到独立路由

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

// 生成不同版本的Swagger文档
const swaggerDocV1 = swaggerJsdoc(swaggerV1Options);
const swaggerDocV2 = swaggerJsdoc(swaggerV2Options);

// 挂载到不同的文档访问路径
app.use('/api-docs/v1', swaggerUi.serve, swaggerUi.setup(swaggerDocV1));
app.use('/api-docs/v2', swaggerUi.serve, swaggerUi.setup(swaggerDocV2));

NestJS 框架下的分组实现 #

如果用NestJS，直接通过@ApiTags()装饰器和Swagger配置即可实现分组：

1. 给控制器打标签

import { Controller, Get } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';

@ApiTags('v1') // 指定该控制器属于v1分组
@Controller('api/v1')
export class V1Controller {
  @Get('users')
  getUsers() {
    return [{ id: 1, name: 'test' }];
  }
}

@ApiTags('v2') // 指定该控制器属于v2分组
@Controller('api/v2')
export class V2Controller {
  @Get('users')
  getUsersV2() {
    return [{ id: 1, name: 'test', email: 'test@example.com' }];
  }
}

2. 配置Swagger模块

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const swaggerConfig = new DocumentBuilder()
    .setTitle('项目API文档')
    .setVersion('1.0')
    .addTag('v1')
    .addTag('v2')
    .build();
  
  const swaggerDocument = SwaggerModule.createDocument(app, swaggerConfig);
  SwaggerModule.setup('api-docs', app, swaggerDocument, {
    swaggerOptions: {
      tagsSorter: 'alpha', // 按字母顺序排序分组
      operationsSorter: 'alpha'
    }
  });

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

这样访问/api-docs就能看到按v1、v2分组的接口列表。

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