TypeScript+Express集成Swagger报错：SwaggerUIBundle未定义求助

云上老周

2026-7-27

TypeScript Express集成Swagger报错解决方案

问题场景

在TypeScript开发的Express项目中集成Swagger，实现代码如下：

...
import swaggerJsDoc from 'swagger-jsdoc'
import swaggerUi from 'swagger-ui-express'

...

const swaggerDefinition ={
    openapi:'3.0.0',
    info:{
        title:'Swagger Test API',
        version:'1.0.0',
    }
}
const options={
    swaggerDefinition,
    apis:['./src/api/routes/*.ts'],
    server:['http://localhost:3000']
}
const swaggerSpec = swaggerJsDoc(options)

app.use('/swagger',swaggerUi.serve,swaggerUi.setup(swaggerSpec))

已安装swagger-jsdoc和swagger-ui-express依赖，但启动开发服务器后出现报错：

Uncaught SyntaxError: Unexpected token '&lt;' (at swagger-ui-bundle.js:3:1)
swagger-ui-standalone-preset.js:3 
Uncaught SyntaxError: Unexpected token '&lt;' (at swagger-ui-standalone-preset.js:3:1)
Uncaught ReferenceError: SwaggerUIBundle is not defined
    at window.onload

解决步骤

调整路由顺序：报错中的<是HTML转义后的<，说明Swagger UI的静态JS文件被返回了HTML（大概率是404页面）。需将app.use('/swagger', ...)代码放在所有其他路由定义之前，尤其是处理404的通配符路由（如app.get('*', ...)）之前。

修正配置参数：options中的server参数无效，swagger-jsdoc要求服务器配置放在swaggerDefinition中，且字段为复数servers：

const swaggerDefinition = {
    openapi: '3.0.0',
    info: {
        title: 'Swagger Test API',
        version: '1.0.0',
    },
    servers: [
        { url: 'http://localhost:3000' }
    ]
}
const options = {
    swaggerDefinition,
    apis: ['./src/api/routes/*.ts'],
}

校验文件路径：若项目先编译TS到dist目录再运行，需将apis路径指向编译后的JS文件：
```
apis: ['./dist/api/routes/*.js']
```
重置依赖：若依赖包损坏导致静态资源加载异常，执行以下命令重置：
```
rm -rf node_modules package-lock.json
npm install
```