koa使用swagger自动生成接口文档

node的swagger现在也用上了注释型的文档，和java的有点类似。主要步骤就两个：swagger配置和注释生成文档

 

 

 

 

话不多说，直接开始

安装

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

　　

直接安装即可

配置

新建 swagger.js 文件，位置放哪都行，只要自己能找到，我放在了根目录，和 packages.js 同级

const router = require('koa-router')() //引入路由函数
const swaggerJSDoc = require('swagger-jsdoc')
const path = require('path')
const swaggerDefinition = {
    info: {
        title: 'blog项目访问地址',
        version: '1.0.0',
        description: 'API',
    },
    host: 'localhost:8000',// 想着改这里，如果不修改，那么接口文档访问地址为：localhost:8000/swagger
    basePath: '/' // Base path (optional)
};
const options = {
    swaggerDefinition,
    apis: [path.join(__dirname, './routes/*.js')], // 写有注解的router的存放地址, 最好path.join()
};
const swaggerSpec = swaggerJSDoc(options)
// 通过路由获取生成的注解文件
router.get('/swagger.json', async function (ctx) {
    ctx.set('Content-Type', 'application/json');
    ctx.body = swaggerSpec;
})
module.exports = router

　　

在 app.js 中新增配置

const swagger = require('./swagger')  // 存放swagger.js的位置，可以自行配置，我放在了根目录
const { koaSwagger } = require('koa2-swagger-ui')

// 接口文档配置
app.use(swagger.routes(), swagger.allowedMethods())
app.use(koaSwagger({
  routePrefix: '/swagger', // 接口文档访问地址
  swaggerOptions: {
    url: '/swagger.json', // example path to json 其实就是之后swagger-jsdoc生成的文档地址
  }
}))

　　

启动项目，访问项目接口地址 + swagger ，我的地址是 http://localhost:8000/swagger

 

添加注释生成文档

1、学习 YAML 语言教程

2、根据 swagger 文档说明，添加注释

参考： https://blog.csdn.net/qq_38734862/article/details/107715579