部分学习来源：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; // 导出路由实例
)
