使用TypeDoc生成Express JS API文档为空的问题求助

以下是针对空文档问题的排查和解决步骤：

1. 确认TypeDoc能定位到源文件 #

TypeDoc默认遵循tsconfig.json的include/exclude规则，如果你的API文件不在include范围内，就会生成空文档。

• 检查tsconfig.json的include配置，确保覆盖你的源码目录：

  {
    "include": ["src/**/*"]
  }
  

• 或者直接在命令行指定要处理的文件/目录，跳过配置文件的限制：

  npx typedoc src/
  

2. 配置entryPoints替代废弃的mode:modules #

旧版的mode:modules已经被移除，现在需要用entryPoints指定TypeDoc的处理入口：

• 命令行方式：

  npx typedoc --entryPoints src/index.ts --out docs
  

• 或者创建typedoc.json配置文件：

  {
    "entryPoints": ["src/index.ts"], // 支持单个文件或多个路径组成的数组
    "out": "docs",
    "tsconfig": "./tsconfig.json"
  }
  

3. 确保代码有可被识别的类型和注释 #

TypeDoc只会提取导出的、带类型注解的成员，以及带JSDoc注释的内容：

• 导出你的路由处理函数或路由对象：

  import { Request, Response } from "express";
  
  /**
   * 获取所有用户信息
   * @route GET /api/users
   * @returns {Array<User>} 用户列表
   */
  export const getUsers = async (req: Request, res: Response) => {
    const users = await User.find();
    res.json(users);
  };
  

• 如果是Express路由实例，确保导出路由：

  import express from "express";
  const router = express.Router();
  
  router.get("/users", getUsers);
  
  export default router;
  

4. 检查版本兼容性 #

确保TypeDoc和TypeScript版本匹配，旧版本可能存在兼容性问题：

# 更新到最新稳定版
npm install typedoc@latest typescript@latest --save-dev

5. 排除无关文件 #

避免TypeDoc处理测试文件、配置文件等无关内容，在typedoc.json中添加exclude：

{
  "entryPoints": ["src/**/*"],
  "exclude": ["src/**/*.test.ts", "src/config/*.ts"]
}

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