express 中使用 Swagger 自动生成接口文档

Swagger 是一个用于描述和文档化 RESTful API 的框架，它提供了一种定义、构建、文档化和消费 RESTful API 的标准方式

在Express.js中，你可以使用Swagger工具自动生成API文档。要实现这一点，你可以按照以下步骤操作：

1. 安装Swagger相关依赖：

   npm install swagger-jsdoc swagger-ui-express --save
   或
   pnpm add swagger-jsdoc swagger-ui-express
   

   • swagger-jsdoc：用于生成 Swagger 规范的 JSDoc 注释解析器。
   • swagger-ui-express：用于在 Express 中提供 Swagger UI。

2. 创建Swagger配置文件（swaggerOptions.js）：

   const swaggerOptions = {
     definition: {
       openapi: '3.0.0',
       info: {
         title: 'Your API',
         version: '1.0.0',
         description: 'API documentation generated with Swagger',
       },
     },
     apis: ['./routes/*.js'], // 指定包含路由的文件路径
   };
   
   module.exports = swaggerOptions;
   

3. 在Express应用中使用Swagger：

   const express = require('express');
   const swaggerJsdoc = require('swagger-jsdoc');
   const swaggerUi = require('swagger-ui-express');
   const swaggerOptions = require('./swaggerOptions'); // 引入上面创建的Swagger配置文件
   
   const app = express();
   
   // 使用swagger-jsdoc创建Swagger规范
   const swaggerSpec = swaggerJsdoc(swaggerOptions);
   
   // 将Swagger规范提供给swagger-ui-express中间件
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
   
   // Your routes go here...
   
   const PORT = process.env.PORT || 3000;
   app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
   

   请注意，上面的代码中的 ./routes/*.js 应该替换为实际包含你的路由的文件路径。

4. 为每个路由添加Swagger注释：

   在你的路由文件中，使用Swagger注释来描述每个API端点的信息。示例：

   /**
    * @swagger
    * /api/user:
    *   get:
    *     summary: Get a list of users
    *     description: Retrieve a list of users from the database.
    *     responses:
    *       '200':
    *         description: A successful response
    *       '500':
    *         description: Internal server error
    */
   router.get('/api/user', (req, res) => {
     // Your route logic here...
     res.status(200).json({ message: 'Successfully retrieved users' });
   });
   

5. 根据环境变量判断是否启用Swagger：

   // 根据环境变量判断是否启用 Swagger
   const isSwaggerEnabled = process.env.NODE_ENV !== 'production';
   if (isSwaggerEnabled) {
      const swaggerSpec = swaggerJsdoc(swaggerOptions);
     app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
   }
   
   

   你可以使用 isSwaggerEnabled 变量来决定是否启用Swagger，通常在非生产环境下开启以便于开发和测试。

通过这些步骤，你的Express.js应用将自动生成具有Swagger文档的API文档。