Typescript Node.js服务中swagger-ui-express仅加载最后定义文档的问题

嘿，这个问题我之前帮人排查过不少次——你遇到的是swagger-ui-express常见的覆盖问题，根源大概率是你要么复用了同一个Swagger文档实例，要么后续的setup调用把之前的配置给覆盖了。给你两种针对性的解决方案，看你需求选：

方案1：为每个控制器单独挂载独立Swagger文档 #

如果你确实需要不同路由路径下显示对应控制器的专属文档，那可以给每个控制器维护自己的OpenAPI规范，然后分别挂载swagger-ui：

首先在每个控制器模块里定义专属的Swagger文档，比如auth.ts：

import { OpenAPIV3 } from 'openapi-types';
import express from 'express';

// 定义Auth模块的专属Swagger文档
export const authSwaggerDoc: OpenAPIV3.Document = {
  openapi: '3.0.0',
  info: {
    title: 'Auth API',
    version: '1.0.0',
    description: '用户认证相关接口'
  },
  paths: {
    '/auth/login': {
      post: {
        summary: '用户登录',
        requestBody: {
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  username: { type: 'string' },
                  password: { type: 'string' }
                },
                required: ['username', 'password']
              }
            }
          }
        },
        responses: {
          '200': { description: '登录成功' },
          '401': { description: '认证失败' }
        }
      }
    }
    // 其他Auth接口定义...
  }
};

// 你的Auth路由逻辑
export const authRoute = express.Router();
authRoute.post('/login', (req, res) => { /* 登录逻辑 */ });

然后在控制器的index.ts里，为每个路由组单独挂载对应的swagger-ui：

import express from 'express';
import passport from 'passport';
import swaggerUi from 'swagger-ui-express';

// 导入各模块的路由和Swagger文档
import { authRoute, authSwaggerDoc } from './auth';
import { botCrudRoute, botCrudSwaggerDoc } from './bot-crud';
import { aiRoutes, aiSwaggerDoc } from './ai';
import { categoryCrudRoute, categoryCrudSwaggerDoc } from './category-crud';

const router = express.Router();

// 挂载Auth路由 + 对应的Swagger文档路径
router.use('/auth', authRoute);
router.use('/auth/docs', swaggerUi.serve, swaggerUi.setup(authSwaggerDoc));

// 挂载Bot CRUD路由 + 对应的Swagger文档路径
router.use('/bot', botCrudRoute);
router.use('/bot/docs', swaggerUi.serve, swaggerUi.setup(botCrudSwaggerDoc));

// 同理挂载其他模块
router.use('/ai', aiRoutes);
router.use('/ai/docs', swaggerUi.serve, swaggerUi.setup(aiSwaggerDoc));

router.use('/category', categoryCrudRoute);
router.use('/category/docs', swaggerUi.serve, swaggerUi.setup(categoryCrudSwaggerDoc));

export default router;

这样每个/xxx/docs路径就会显示对应模块的独立文档，不会互相覆盖。

方案2：合并所有控制器文档为统一Swagger页面 #

如果你的目标是在同一个Swagger页面展示所有接口，那需要把各模块的API定义合并到同一个OpenAPI对象里：

首先创建一个根级的Swagger模板文件，比如swagger.config.ts：

import { OpenAPIV3 } from 'openapi-types';

export const baseSwaggerDoc: OpenAPIV3.Document = {
  openapi: '3.0.0',
  info: {
    title: '我的Node.js服务API',
    version: '1.0.0',
    description: '所有业务模块的接口汇总'
  },
  paths: {} // 空paths，后续合并各模块的定义
};

然后在每个控制器模块里只导出自己的paths对象，比如auth.ts：

import { OpenAPIV3 } from 'openapi-types';
import express from 'express';

// 仅导出Auth模块的paths定义
export const authPaths: OpenAPIV3.PathsObject = {
  '/auth/login': { /* 接口定义... */ },
  '/auth/logout': { /* 接口定义... */ }
};

// 路由逻辑不变
export const authRoute = express.Router();
// ...

回到控制器的index.ts，合并所有paths并挂载统一的Swagger文档：

import express from 'express';
import passport from 'passport';
import swaggerUi from 'swagger-ui-express';
import { baseSwaggerDoc } from '../swagger.config';

// 导入各模块的路由和paths定义
import { authRoute, authPaths } from './auth';
import { botCrudRoute, botCrudPaths } from './bot-crud';
import { aiRoutes, aiPaths } from './ai';
import { categoryCrudRoute, categoryCrudPaths } from './category-crud';

// 合并所有模块的paths到基础文档
baseSwaggerDoc.paths = {
  ...baseSwaggerDoc.paths,
  ...authPaths,
  ...botCrudPaths,
  ...aiPaths,
  ...categoryCrudPaths
};

const router = express.Router();

// 挂载所有业务路由
router.use('/auth', authRoute);
router.use('/bot', botCrudRoute);
router.use('/ai', aiRoutes);
router.use('/category', categoryCrudRoute);

// 挂载统一的Swagger文档页面
router.use('/docs', swaggerUi.serve, swaggerUi.setup(baseSwaggerDoc));

export default router;

额外排查提示 #

• 检查你有没有在多个地方重复调用swaggerUi.setup同一个文档对象，后续的调用会直接覆盖之前的配置。
• 如果用了swagger-jsdoc生成文档，要确保扫描范围包含了所有控制器文件，别只扫了最后一个模块。
• 路由挂载顺序不影响Swagger文档显示，但业务路由的顺序会影响请求匹配，这点注意下就行。

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