Swagger UI无法在浏览器显示，本地访问出现空白加载页面求助

核心问题分析 #

从提供的代码和现象来看，主要存在以下几个导致Swagger页面空白并持续加载的问题：

1. OpenAPI定义拼写错误 #

配置中存在两处关键拼写错误，导致生成的OpenAPI规范结构无效：

• compontents → 正确应为 components
• securitySchemas → 正确应为 securitySchemes

这两个错误会让swagger-jsdoc无法生成符合规范的OpenAPI文档，进而导致Swagger UI解析失败，页面卡住加载。

2. Swagger UI配置冲突 #

代码中同时使用了两种Swagger UI加载逻辑：

• 直接传入本地生成的openapiSpecification到swaggerUi.setup()
• 在swaggerOptions中指定url: "/api-docs/swagger.json"让UI远程加载文档

这种冲突会导致Swagger UI同时执行两种加载逻辑，引发加载阻塞。

3. 路由文件JSDoc注释问题 #

如果./backend/api/V1/routes/*.routes.js路径下的路由文件存在JSDoc注释格式错误、语法错误，会导致swagger-jsdoc生成的OpenAPI规范缺失关键内容（比如paths字段），进而让Swagger UI无法渲染页面。

分步解决方法 #

1. 修正拼写错误 #

修改options中的定义部分，纠正拼写错误：

const options = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "Docs",
      version,
    },
    components: { // 修正拼写
      securitySchemes: { // 修正拼写
        bearerAuth: {
          type: "http",
          scheme: "bearer",
          bearerFormat: "JWT",
        },
      },
    },
    security: [
      {
        bearerAuth: [],
      },
    ],
  },

  apis: ["./backend/api/V1/routes/*.routes.js"],
  // 移除冲突的swaggerOptions.url配置
};

2. 解决配置冲突 #

选择以下一种方式调整Swagger UI配置：

方式一：直接使用本地生成的规范（推荐）

移除swaggerOptions.url配置，保留本地传入的规范：

const openapiSpecification = swaggerJsdoc(options);
function swaggerDocs(app, port) {
  // 仅使用本地生成的spec，无需指定远程URL
  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(openapiSpecification));
  app.get("/api-docs.json", (req, res) => {
    res.setHeader("Content-Type", "application/json");
    res.send(openapiSpecification);
  });
  logger.info(`Swagger docs are running at http://localhost:${port}/api-docs`);
}

方式二：通过URL加载规范

如果需要通过URL加载，需确保setup方法不传入本地spec，并修正URL路径（你的接口是/api-docs.json而非/api-docs/swagger.json）：

const openapiSpecification = swaggerJsdoc(options);
function swaggerDocs(app, port) {
  const swaggerOptions = {
    url: "/api-docs.json", // 修正路径
  };
  // setup方法传入null，让UI通过指定URL加载
  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(null, swaggerOptions));
  app.get("/api-docs.json", (req, res) => {
    res.setHeader("Content-Type", "application/json");
    res.send(openapiSpecification);
  });
  logger.info(`Swagger docs are running at http://localhost:${port}/api-docs`);
}

3. 检查路由文件注释 #

遍历./backend/api/V1/routes/*.routes.js下的所有路由文件，确保JSDoc注释符合swagger-jsdoc规范，示例：

/**
 * @swagger
 * /api/v1/users:
 *   get:
 *     summary: 获取用户列表
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: 成功返回用户列表
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: string
 *                   name:
 *                     type: string
 */
router.get('/users', (req, res) => {
  // 路由逻辑
});

4. 验证生成的OpenAPI规范 #

在代码中添加日志输出，检查生成的规范是否有效：

const openapiSpecification = swaggerJsdoc(options);
console.log(JSON.stringify(openapiSpecification, null, 2)); // 输出完整规范

启动服务后，查看控制台输出的JSON是否包含paths、components等关键字段，结构是否符合OpenAPI 3.0标准。

5. 重置依赖排除版本问题 #

如果以上步骤无效，可能是依赖包损坏或版本冲突，执行以下命令重置依赖：

rm -rf node_modules package-lock.json
npm install

重启服务后再次测试Swagger页面。

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