Node.js IIFE架构下swagger-autogen无API输出问题求助

问题根源 #

1. 未扫描到实际路由文件：你仅将routes.js加入扫描列表，但真正的API接口定义在./route_handlers/auth.js中，swagger-autogen默认不会递归解析依赖文件，因此无法识别这些接口。
2. 输出文件路径处理错误：使用fs.openSync会返回文件描述符（数字格式）而非文件路径，导致swagger-autogen无法正常生成JSON文件。
3. 扫描入口选择不当：routes.js仅负责将路由挂载到Express实例，直接扫描它无法追踪完整的路由注册流程，应将app.js作为扫描入口——它才是初始化Express实例并挂载所有路由的核心文件。

具体修复步骤 #

1. 修正swagger.js核心代码 #

将扫描入口改为app.js，同时修复输出文件的创建逻辑：

const swaggerAutogen = require("swagger-autogen")();
const fs = require("fs");
const path = require("path");

// 替换为你的实际应用名称和描述
const appName = "你的应用名称";
const appDesc = "你的应用描述";

const doc = {
  info: {
    title: appName,
    description: appDesc,
  },
  host: "localhost:5001",
  basePath: "/",
  schemes: ["http", "https"],
  consumes: ["application/json"],
  produces: ["application/json"],
  tags: [
    {
      name: appName,
      description: appDesc,
    },
  ],
};

const outputDir = "./public/api-docs";
// 先确保目录存在，不存在则递归创建
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true });
}
const outputFile = path.join(outputDir, "swagger-output1.json");

// 以app.js为扫描入口，自动追踪所有挂载的路由
const endpointsFiles = ["./app.js"];
swaggerAutogen(outputFile, endpointsFiles, doc);

2. 确保路由文件写法符合识别规则 #

在./route_handlers/auth.js中使用标准Express路由写法，若需要更详细的文档，可添加JSDoc注释（不添加也能识别基础路由）：

const express = require("express");
const router = express.Router();

// 示例：带注释的登录接口
/**
 * @swagger
 * /api/v1/login:
 *   post:
 *     tags: [Auth]
 *     description: 用户登录接口
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               username:
 *                 type: string
 *               password:
 *                 type: string
 *     responses:
 *       200:
 *         description: 登录成功
 */
router.post("/login", (req, res) => {
  // 你的接口逻辑
  res.json({ status: "success", message: "登录成功" });
});

module.exports = router;

3. 调整执行顺序 #

在package.json中添加脚本，先生成Swagger文档再启动应用：

{
  "scripts": {
    "swagger": "node swagger.js",
    "start": "node app.js"
  }
}

执行npm run swagger生成文档后，再启动项目。

额外提示 #

• 若路由分散在多个文件中，可直接以app.js作为扫描入口（更省心），它会加载所有路由，swagger-autogen会顺着依赖链扫描到所有接口；也可将所有路由文件逐一加入endpointsFiles。
• 你使用的swagger-autogen@2.23.5与Express@4.17.1版本兼容，无需更换版本。

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