swagger自动生成nodejs接口

在一个Node.js项目中添加Swagger可以帮助你创建和维护API文档，以便更好地理解和测试你的API。下面是将Swagger集成到Node.js项目中的一般步骤：

安装Swagger相关库：使用npm或者yarn安装Swagger相关的库，包括swagger-jsdoc和swagger-ui-express。

js 复制代码

npm install swagger-jsdoc swagger-ui-express

2.创建Swagger配置文件：在项目的根目录下创建一个Swagger配置文件，例如swaggerConfig.js。 const swaggerJsdoc = require('swagger-jsdoc');

js 复制代码

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

// Swagger配置选项
const options = {
  definition: {
    openapi: '3.0.0', // 版本号
    info: {
      title: 'Node.js API', // API名称
      version: '1.0.0', // API版本
      description: 'API 文档示例', // API描述
    },
  },
  apis: ['./routes/*.js'], // 包含API文档的路由文件的路径
};

const swaggerSpec = swaggerJsdoc(options);

module.exports = swaggerSpec;

这个配置文件中定义了一些基本信息，包括API名称、版本和描述，以及指定了包含API文档的路由文件的路径。

3.创建Swagger路由：在你的项目中，你可以创建一个专门用于Swagger的路由文件，例如swagger.js，用于展示Swagger UI。这个路由将使用swagger-ui-express库来展示API文档。

复制代码

js 复制代码

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('../swaggerConfig.js'); // 导入Swagger配置

const router = express.Router();

router.use('/', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

module.exports = router;

4.在主应用程序中使用Swagger路由：在你的主应用程序文件（通常是app.js或server.js）中引入并使用Swagger路由：

js 复制代码

const express = require('express');
const swaggerRouter = require('./routes/swagger'); // 导入Swagger路由
const app = express();

// 其他路由和中间件...

// 使用Swagger路由
app.use('/api-docs', swaggerRouter);

// 启动服务器
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

5.生成API文档：使用注释来描述你的API端点，以便Swagger可以从你的代码中生成文档。在每个路由处理函数的前面添加注释，例如：

js 复制代码

/**
 * @swagger
 * /api/some-endpoint:
 *   get:
 *     summary: 获取某些内容
 *     description: 获取某些内容的示例请求
 *     parameters:
 *       - in: header
 *         name: Authorization
 *         description: 认证令牌
 *         required: true
 *         schema:
 *           type: string
 *       - in: header
 *         name: Content-Type
 *         description: 请求内容类型
 *         required: true
 *         schema:
 *           type: string
 *           default: application/json
 *     responses:
 *       200:
 *         description: 成功获取内容
 *       401:
 *         description: 未经授权
 *       500:
 *         description: 服务器错误
 */
router.get('/api/some-endpoint', (req, res) => {
  // 处理请求的逻辑
});

6.启动应用程序：使用node或其他Node.js应用程序启动工具来启动你的应用程序。然后，访问/api-docs路径以查看生成的Swagger文档。

js 复制代码

node app.js

看效果