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

news2025/1/31 21:46:53

部分学习来源: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/basePath
    schemes: ['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 /docs
        swaggerOptions: {
            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.coloradmin.cn/o/2288064.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

Docker/K8S

文章目录 项目地址一、Docker1.1 创建一个Node服务image1.2 volume1.3 网络1.4 docker compose 二、K8S2.1 集群组成2.2 Pod1. 如何使用Pod(1) 运行一个pod(2) 运行多个pod 2.3 pod的生命周期2.4 pod中的容器1. 容器的生命周期2. 生命周期的回调3. 容器重启策略4. 自定义容器启…

leetcode——排序链表(java)

给你链表的头结点 head ,请将其按 升序 排列并返回 排序后的链表 。 示例 1: 输入:head [4,2,1,3] 输出:[1,2,3,4] 示例 2: 输入:head [-1,5,3,4,0] 输出:[-1,0,3,4,5] 示例 3: …

基于springboot的校园部门资料管理系统

博主介绍:java高级开发,从事互联网行业多年,熟悉各种主流语言,精通java、python、php、爬虫、web开发,已经做了多年的设计程序开发,开发过上千套设计程序,没有什么华丽的语言,只有实…

数据结构初阶之堆的介绍与堆的实现

一、堆的概念与结构 如果有一个关键码的集合,把它的所有元素按完全二叉树的顺序存储在一个一维数组中,并满足:,则称为小堆(或大堆)。 将根结点最大的堆叫做最大堆或大根堆,根结点最小的堆叫做…

Day29(补)-【AI思考】-精准突围策略——从“时间贫困“到“效率自由“的逆袭方案

文章目录 精准突围策略——从"时间贫困"到"效率自由"的逆袭方案**第一步:目标熵减工程(建立四维坐标)** 与其他学习方法的结合**第二步:清华方法本土化移植** 与其他工具对比**~~第三步:游戏化改造…

docker中运行的MySQL怎么修改密码

1,进入MySQL容器 docker exec -it 容器名 bash 我运行了 docker ps命令查看。正在运行的容器名称。可以看到MySQL的我起名为db docker exec -it db bash 这样就成功的进入到容器中了。 2,登录MySQL中 mysql -u 用户名 -p 回车 密码 mysql -u root -p roo…

leetcode——二叉树的中序遍历(java)

给定一个二叉树的根节点 root ,返回 它的 中序 遍历 。 示例 1: 输入:root [1,null,2,3] 输出:[1,3,2] 示例 2: 输入:root [] 输出:[] 示例 3: 输入:root [1] 输出…

信息安全专业优秀毕业设计选题汇总:热点选题

目录 前言 毕设选题 开题指导建议 更多精选选题 选题帮助 最后 前言 大家好,这里是海浪学长毕设专题! 大四是整个大学期间最忙碌的时光,一边要忙着准备考研、考公、考教资或者实习为毕业后面临的升学就业做准备,一边要为毕业设计耗费大量精力。学长给大家整理…

Java---猜数字游戏

本篇文章所实现的是Java经典的猜数字游戏 , 运用简单代码来实现基本功能 目录 一.题目要求 二.游戏准备 三.代码实现 一.题目要求 随机生成一个1-100之间的整数(可以自己设置区间),提示用户猜测,猜大提示"猜大了",…

SAP系统中的主要采购类型/采购模式总结

在 SAP 系统中,采购类型主要有以下几种: 一、标准采购订单(Standard Purchase Order) 描述:这是最常用的采购类型,用于一次性采购货物或服务。采购部门根据需求部门提出的采购申请,向供应商发出采购订单,明确规定了采购的物料、数量、价格、交货日期等详细信息。 应…

论文笔记(六十三)Understanding Diffusion Models: A Unified Perspective(五)

Understanding Diffusion Models: A Unified Perspective(五) 文章概括基于得分的生成模型(Score-based Generative Models) 文章概括 引用: article{luo2022understanding,title{Understanding diffusion models: A…

ThinkPHP 8模型与数据的插入、更新、删除

【图书介绍】《ThinkPHP 8高效构建Web应用》-CSDN博客 《2025新书 ThinkPHP 8高效构建Web应用 编程与应用开发丛书 夏磊 清华大学出版社教材书籍 9787302678236 ThinkPHP 8高效构建Web应用》【摘要 书评 试读】- 京东图书 使用VS Code开发ThinkPHP项目-CSDN博客 编程与应用开…

项目升级Sass版本或升级Element Plus版本遇到的问题

项目升级Sass版本或升级Element Plus版本遇到的问题 如果项目有需求需要用到高版本的Element Plus组件,则需要升级相对应的sass版本,Element 文档中有提示,2.8.5及以后得版本,sass最低支持的版本为1.79.0,所升级sass、…

基于OSAL的嵌入式裸机事件驱动框架——整体架构调度机制

参考B站up主【架构分析】嵌入式祼机事件驱动框架 感谢大佬分享 任务ID : TASK_XXX TASK_XXX 在系统中每个任务的ID是唯一的,范围是 0 to 0xFFFE,0xFFFF保留为SYS_TSK_INIT。 同时任务ID的大小也充当任务调度的优先级,ID越大&#…

Three.js 后期处理(Post-Processing)详解

目录 前言 一、什么是后期处理? 二、Three.js 后期处理的工作流程 2.1 创建 EffectComposer 2.2 添加渲染通道(Render Pass) 2.3 应用最终渲染 三、后期处理实现示例 3.1 基础代码 四、常见的后期处理效果 4.1 辉光效果&#xf…

HTML特殊符号的使用示例

目录 一、基本特殊符号的使用 1、空格符号: 2、小于号 和 大于号: 3、引号: 二、版权、注册商标符号的使用 1、版权符号:© 2、注册商标符号: 三、数学符号的使用 四、箭头符号的使用 五、货币符号的使用…

JAVA实战开源项目:在线文档管理系统(Vue+SpringBoot) 附源码

本文项目编号 T 038 ,文末自助获取源码 \color{red}{T038,文末自助获取源码} T038,文末自助获取源码 目录 一、系统介绍二、演示录屏三、启动教程四、功能截图五、文案资料5.1 选题背景5.2 国内外研究现状5.3 可行性分析 六、核心代码6.1 查…

快速分析LabVIEW主要特征进行判断

在LabVIEW中,快速分析程序特征进行判断是提升开发效率和减少调试时间的重要技巧。本文将介绍如何高效地识别和分析程序的关键特征,从而帮助开发者在编写和优化程序时做出及时的判断,避免不必要的错误。 ​ 数据流和并行性分析 LabVIEW的图形…

UE学习日志#15 C++笔记#1 基础复习

1.C20的import 看看梦开始的地方&#xff1a; import <iostream>;int main() {std::cout << "Hello World!\n"; } 经过不仔细观察发现梦开始的好像不太一样&#xff0c;这个import是C20的模块特性 如果是在VS里编写的话&#xff0c;要用这个功能需要新…

Deep Seek R1本地化部署

目录 说明 一、下载ollama 二、在ollama官网下载模型 三、使用 后记 说明 操作系统&#xff1a;win10 使用工具&#xff1a;ollama 一、下载ollama 从官网下载ollama&#xff1a; ollama默认安装在C盘&#xff0c;具体位置为C:\Users\用户名\AppData\Local\Programs\O…