【Node.js】Koa2 整合接口文档

server/2025/2/1 9:38:56/

部分学习来源:https://blog.csdn.net/qq_38734862/article/details/107715579

依赖

// koa2-swagger-ui UI视图组件  swagger-jsdoc 识别写的 /***/ 转 json
npm install koa2-swagger-ui swagger-jsdoc --save

配置

在这里插入图片描述

config\swaggerConfig.js

const Router = require('@koa/router'); // 引入 Router 类
const path = require('node:path');
const swaggerJSDoc = require('swagger-jsdoc');const swaggerDefinition = {info: {description:'This is a sample server Koa2 server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters.',version: '1.0.0',title: 'Koa2_server Swagger',},host: 'localhost:4000',basePath: '/', // Base path (optional), host/basePathschemes: ['http'],
};const options = {swaggerDefinition,// 写有注解的router的存放地址(当你新增swagger时文档里没显示出来的话那么就是这边地址没有加进去)apis: ['./routes/*.js'] // 注意这里的路径!!!
};const swaggerSpec = swaggerJSDoc(options);// 创建一个新的 Router 实例
const router = new Router();// 通过路由获取生成的注解文件
router.get('/swagger.json', async ctx => {ctx.set('Content-Type', 'application/json');ctx.body = swaggerSpec;
});module.exports = router;

入口文件 app.js 注册:

const Koa = require('koa');
const app = new Koa();
const {koaSwagger} = require("koa2-swagger-ui");const attractionRoute = require('./routes/attractionsRoute'); // 添加: 引入景点路由
const swaggerConfig = require('./config/swaggerConfig');// 使用 Swagger 路由
app.use(swaggerConfig.routes()).use(swaggerConfig.allowedMethods());// 使用景点路由
app.use(attractionRoute.routes()).use(attractionRoute.allowedMethods());
// 使用 Swagger UI
app.use(koaSwagger({routePrefix: '/swagger', // host at /swagger instead of default /docsswaggerOptions: {url: '/swagger.json' // example path to json}})
);app.listen(4000, () => {console.log('Server is running on port 4000');
});

配置完后打开 http://localhost:4000/swagger 可以得到文档可视化界面,http://localhost:4000/swagger.json 可以看到 swagger 文档配置。

在这里插入图片描述

routes 的 swagger 文档注释规范可以参考OpenAPI规范,比如 OpenAPI规范示例。

我的 attrtionsRoute.js 示例:

const Router = require('@koa/router'); // 添加: 引入路由模块
const router = new Router({ prefix: '/api/scenic' }); // 修改: 创建路由实例,并设置前缀const attractionsController = require('../controllers/attractionsController');// 获取景点列表
// 生成swagger注释
/*** @swagger* /api/scenic/list:*   get:*     summary: 获取景点列表*     responses:*       200:*         description: 景点列表*/
router.get('/list', attractionsController.getAttractionsList);// 获取景点详情
// 生成swagger注释
/*** @swagger* /api/scenic/{id}:*   get:*     summary: 获取景点详情*     parameters:*       - in: path*         name: id*         required: true*         schema:*           type: string*         description: 景点ID*     responses:*       200:*         description: 景点详情*/
router.get('/:id', attractionsController.getAttractionById);// 添加新景点
// 生成swagger注释
/*** @swagger* /api/scenic/add:*   post:*     summary: 添加新景点*     requestBody:*       required: true*       content:*         application/json:*           schema:*             type: object*             properties:*               name:*                 type: string*               description:*                 type: string*     responses:*       201:*         description: 景点添加成功*/
router.post('/add', attractionsController.addAttraction);// 更新景点信息
// 生成swagger注释
/*** @swagger* /api/scenic/update/{id}:*   put:*     summary: 更新景点信息*     parameters:*       - in: path*         name: id*         required: true*         schema:*           type: string*         description: 景点ID*     requestBody:*       required: true*       content:*         application/json:*           schema:*             type: object*             properties:*               name:*                 type: string*               description:*                 type: string*     responses:*       200:*         description: 景点更新成功*/
router.put('/update/:id', attractionsController.updateAttraction);// 删除景点
// 生成swagger注释
/*** @swagger* /api/scenic/delete/{id}:*   delete:*     summary: 删除景点*     parameters:*       - in: path*         name: id*         required: true*         schema:*           type: string*         description: 景点ID*     responses:*       200:*         description: 景点删除成功*/
router.delete('/delete/:id', attractionsController.deleteAttraction);// 添加评论
// 生成swagger注释
/*** @swagger* /api/scenic/comment/{id}:*   post:*     summary: 添加评论*     parameters:*       - in: path*         name: id*         required: true*         schema:*           type: string*         description: 景点ID*     requestBody:*       required: true*       content:*         application/json:*           schema:*             type: object*             properties:*               comment:*                 type: string*     responses:*       201:*         description: 评论添加成功*/
router.post('/comment/:id', attractionsController.addComment);// 获取景点评论
// 生成swagger注释
/*** @swagger* /api/scenic/comments/{id}:*   get:*     summary: 获取景点评论*     parameters:*       - in: path*         name: id*         required: true*         schema:*           type: string*         description: 景点ID*     responses:*       200:*         description: 景点评论列表*/
router.get('/comments/:id', attractionsController.getComments);module.exports = router; // 导出路由实例

http://www.ppmy.cn/server/164032.html

相关文章

【Redis】List 类型的介绍和常用命令

1. 介绍 Redis 中的 list 相当于顺序表,并且内部更接近于“双端队列”,所以也支持头插和尾插的操作,可以当做队列或者栈来使用,同时也存在下标的概念,不过和 Java 中的下标不同,Redis 支持负数下标&#x…

计算机网络 (61)移动IP

前言 移动IP(Mobile IP)是由Internet工程任务小组(Internet Engineering Task Force,IETF)提出的一个协议,旨在解决移动设备在不同网络间切换时的通信问题,确保移动设备可以在离开原有网络或子网…

react项目表格内容轮播,DataV-React轮播表的使用

项目中想要实现表格表头固定不动,表格行内容轮播呈现的效果,antd中的table无法实现,使用DataV-React轮播表来实现。 官网地址:介绍 | DataV-React 轮播表 | DataV-React 1. 安装 npm 安装 npm install jiaminghi/data-view-r…

JVM_类的加载、链接、初始化、卸载、主动使用、被动使用

①. 说说类加载分几步? ①. 按照Java虚拟机规范,从class文件到加载到内存中的类,到类卸载出内存为止,它的整个生命周期包括如下7个阶段: 第一过程的加载(loading)也称为装载验证、准备、解析3个部分统称为链接(Linking)在Java中数据类型分为基本数据类型和引用数据…

“大模型横扫千军”背后的大数据挖掘--浅谈MapReduce

文章目录 O 背景知识1 数据挖掘2 邦费罗尼原则3 TF.IDF4 哈希函数5 分布式文件系统 一、MapReduce基本介绍1. Map 任务2. 按键分组3. Reduce 任务4. 节点失效处理5.小测验:在一个大型语料库上有100个map任务和若干reduce任务: 二、基于MapReduce的基本运…

Canny 边缘检测

步骤 1.降噪 应用高斯滤波器,以平滑图像,滤除噪声。 边缘检测易受噪声影响,所以使用高斯滤波器平滑图像,降低噪声。 2.梯度 计算图像中每个像素点的梯度大小和方向。 计算大小 Sobel算子是一种常用的边缘检测滤波器&#xff…

【fly-iot飞凡物联】(20):2025年总体规划,把物联网整套技术方案和实现并落地,完成项目开发和课程录制。

前言 fly-iot飞凡物联专栏: https://blog.csdn.net/freewebsys/category_12219758.html 1,开源项目地址进行项目开发 https://gitee.com/fly-iot/fly-iot-platform 完成项目开发,接口开发。 把相关内容总结成文档,并录制课程。…

android studio生成jsk

JKS 文件(Java KeyStore)是 Android 开发中用于签名 APK 的密钥库文件。它包含用于签名的私钥和公钥,并保护其不被未授权使用。 在 Android 开发中,所有的 APK 文件在发布之前必须使用签名密钥进行签名: 调试签名&am…