如何通过Node.js代码注释自动生成swagger.json文件？

步骤1：安装核心依赖 #

使用swagger-jsdoc工具，它能解析代码中的JSDoc风格Swagger注释并生成规范的swagger.json文件。执行安装命令：

npm install swagger-jsdoc --save-dev

步骤2：创建Swagger配置文件 #

在项目根目录新建swagger.config.js，配置基础文档信息并指定要扫描的路由文件路径：

const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0', // 匹配你的Swagger版本
    info: {
      title: '你的API项目名称',
      version: '1.0.0',
      description: 'API接口自动生成文档',
    },
  },
  apis: ['./routes/**/*.js'], // 根据你的项目结构调整，指定包含接口注释的文件路径
};

const swaggerSpec = swaggerJsdoc(options);
module.exports = swaggerSpec;

步骤3：在接口代码中添加Swagger注释 #

在路由/接口函数上方添加符合Swagger规范的JSDoc注释，示例如下：

/**
 * @swagger
 * /api/users/{id}:
 *   get:
 *     summary: 根据ID获取单个用户信息
 *     description: 传入用户ID，返回对应用户的详细数据
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 用户唯一ID
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: 请求成功，返回用户对象
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id:
 *                   type: string
 *                 name:
 *                   type: string
 *                 email:
 *                   type: string
 *       404:
 *         description: 未找到对应ID的用户
 */
router.get('/api/users/:id', (req, res) => {
  // 接口业务逻辑
  res.json({ id: req.params.id, name: '张三', email: 'zhangsan@example.com' });
});

步骤4：添加生成swagger.json的脚本 #

在package.json的scripts字段中添加生成命令：

"scripts": {
  "generate-swagger": "node -e \"const swaggerSpec = require('./swagger.config.js'); const fs = require('fs'); fs.writeFileSync('./swagger.json', JSON.stringify(swaggerSpec, null, 2))\""
}

执行以下命令即可自动生成swagger.json文件：

npm run generate-swagger

生成的swagger.json可以直接导入你已有的swagger-ui前端使用。

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