部分學習來源：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; // 導出路由實例