当前位置：首页 > news >正文

node配置swagger

news 2025/7/8 9:24:14

安装swagger

npm install swagger-jsdoc swagger-ui-express

创建 swagger.js 配置文件

const path = require('path');
const express = require('express');
const swaggerUI = require('swagger-ui-express');
const swaggerJsDoc = require('swagger-jsdoc'); // 修改 `swaggerDoc` 为 `swaggerJsDoc`// 配置 swagger-jsdoc 选项
const options = {definition: {openapi: '3.0.0',info: {title: '企业管理后台API文档', // 标题信息version: '1.0.0',description: '企业级管理后台共用接口API文档',},},// 去指定路由下收集 swagger 注释apis: [ './routers/*.js'], // 注意路径是否正确
};// 使用 swaggerJsDoc 生成规范的 swaggerSpec
const swaggerSpec = swaggerJsDoc(options);// 定义 `swaggerJson` 方法，用于返回 swagger 文档的 JSON 数据
const swaggerJson = function (req, res) {res.setHeader('Content-Type', 'application/json');res.send(swaggerSpec);
};// 定义 `swaggerInstall` 方法，用于将 swagger 安装到应用中
const swaggerInstall = function (app) {if (!app) {app = express(); // 如果没有传入 app，则创建一个新的 express 实例}// 开放 JSON 格式的文档接口app.get('/swagger.json', swaggerJson);// 使用 swaggerSpec 生成 swagger 文档页面，并开放在指定路由 '/swagger'app.use('/swagger', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
};// 导出 `swaggerInstall` 方法供其他模块使用
module.exports = swaggerInstall;

设置 Swagger 注释规范

/*** @swagger* /users:*   get:*     summary: Retrieve a list of users*     responses:*       200:*         description: A list of users*         content:*           application/json:*             schema:*               type: array*               items:*                 type: object*                 properties:*                   id:*                     type: integer*                     example: 1*                   name:*                     type: string*                     example: John Doe*/
app.get('/users', (req, res) => {res.json([{ id: 1, name: 'John Doe' },{ id: 2, name: 'Jane Doe' },]);
});

配置 Swagger UI

在主应用文件（如app.js）中配置Swagger UI中间件：

const express=require('express')
const app=express()
const cors=require('cors')
const bodyParser=require('body-parser')
const menu=require('./routers/menu')
const main=require('./routers/main')
const area =require('./routers/area')
const upload =require('./routers/upload')
const user=require('./routers/user')
const swaggerInstall = require('./utils/swagger')// 引入swagger
app.use(express.static('./data/upload'))
app.use(bodyParser.json())
app.use(bodyParser.urlencoded({extended: true}));
app.use(cors());
app.use('/api/menu',menu)
app.use('/api/main',main)
app.use('/api/area',area)
app.use('/api/upload',upload)
app.use('/api/user',user)
swaggerInstall(app) // 注册swagger
app.use(function(err,req,res,next){console.info(err.stack)res.status('500').send('服务端出错了')
})app.listen('3030',function(){console.log('服务器正在监听3030端口')
})

启动node服务

node app.js 具体看自己配置node启动命令是啥

启动访问设置地址+/swager/