swagger-ui-express中无法在Authorization头传递Bearer Token

运行express/Node应用，使用swagger-ui-express@^4.5.0生成API文档，已配置所有接口需携带JWT Bearer Token。Swagger文档可正常加载，添加securitySchemes及相关配置后出现绿色Authorize按钮，但输入Token发送请求时，加载动画持续转圈，请求从未发出，morgan日志无记录，应用终端无报错，但Chrome浏览器控制台存在错误。

相关代码配置：

app.js 中的Swagger路由配置 #

// Single entry point for swagger docs
router.use(
  '/swaggerDocs',
  swaggerDoc.serve,
  swaggerDoc.setup(swaggerDocumentation),
);

swaggerDocumentation配置文件 #

import getCountryRegions from './getCountryRegions.doc.js';

export default {
  openapi: '3.0.3',
  info: {
    title: 'Node/express rest api app',
    version: '0.0.1',
  },
  components: {
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        in: 'header',
        name: 'Authorization',
        description: 'Bearer Token',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    },
  },
  security: {
    bearerAuth: [],
  },
  servers: [
    {
      url: 'http://localhost:3010/api',
      description: 'Local server',
    },
  ],
  paths: {
    ...getCountryRegions,
  },
};

1. 修正OpenAPI配置中security字段的格式错误 #

OpenAPI 3.x规范中，security字段要求是数组类型，而非对象。当前配置的对象格式会导致Swagger UI无法正确解析授权规则，进而阻塞请求发送。

修改swaggerDocumentation中的security字段：

// 错误写法
security: {
  bearerAuth: [],
},

// 正确写法
security: [
  { bearerAuth: [] },
],

2. 查看Chrome控制台的具体错误信息 #

浏览器控制台的错误是定位问题的核心依据，常见可能的错误场景：

• 脚本解析错误：因OpenAPI配置格式错误导致Swagger UI脚本执行失败
• CORS跨域问题：若API服务器与Swagger UI的端口/域名不一致，需在express中配置CORS规则允许Swagger域名的请求
• Token格式问题：确认输入Token时未额外添加Bearer 前缀（Swagger UI的bearerAuth会自动补全该前缀）

3. 升级swagger-ui-express版本 #

swagger-ui-express@4.5.0对OpenAPI 3.0的支持存在部分兼容性问题，建议升级至同大版本的最新版本：

npm update swagger-ui-express

4. 调整Swagger UI初始化配置 #

在swaggerDoc.setup中添加swaggerOptions配置，确保授权状态正确持久化并开启调试相关选项：

router.use(
  '/swaggerDocs',
  swaggerDoc.serve,
  swaggerDoc.setup(swaggerDocumentation, {
    swaggerOptions: {
      persistAuthorization: true, // 持久化授权状态
      tryItOutEnabled: true,
    },
  }),
);

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