用Node.js自动生成API文档，开发效率翻倍

做后端开发时，写API文档是个绕不开的活。改了接口字段，文档也得跟着改，一来二去容易出错。很多人干脆不写文档，靠口头沟通，结果前端同事常跑来问：‘这个接口到底返回啥？’

为什么需要自动生成文档？

手动维护文档费时又容易遗漏。比如你加了个新的用户注册接口，忘了更新文档，前端按旧格式传参，调不通还查半天。如果能在写代码的同时，把文档也一起生成，省事又靠谱。

Node.js生态里有不少工具能自动从代码注释生成API文档，JSDoc、Swagger（OpenAPI）配合Express用起来都很顺手。

用Swagger + Express快速出文档

假设你正在用Express写一个用户管理接口，可以借助swagger-jsdoc和swagger-ui-express这两个包。

先装依赖：

npm install swagger-jsdoc swagger-ui-express

然后在项目里配置Swagger选项：

const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '用户API文档',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // 告诉它去哪读注释
};

const swaggerSpec = swaggerJsDoc(options);

接着在路由文件里加注释，比如userRoutes.js：

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: 获取所有用户
 *     responses:
 *       200:
 *         description: 返回用户列表
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                   name:
 *                     type: string
 */
router.get('/api/users', getUsers);

最后把UI挂到Express应用上：

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

启动服务后，访问 http://localhost:3000/api-docs，就能看到带交互界面的API文档，点一下就能测试接口。

其他选择：用JSDoc生成代码说明

如果你不需要花哨的交互页面，只是想让团队成员看懂接口怎么用，JSDoc更轻量。它能根据注释生成静态HTML文档，适合嵌入项目Wiki或内部知识库。

比如这样写注释：

/**
 * 查询订单详情
 * @param {number} orderId - 订单ID
 * @returns {Object} 订单对象，包含status和amount字段
 */
function getOrder(orderId) {
  // ...
}

运行 npx jsdoc src 后，就会生成对应的网页文档。

这类工具最大的好处是“文档即代码”。改代码时顺手改注释，文档就不会脱节。新同事接手项目，打开/docs一看全明白，不用到处问人。

现在很多公司都把API文档生成集成进CI流程，代码合并后自动部署最新文档。谁也没法偷懒，文档永远跟代码同步。