node koa2 swaggerUI 生成接口文档

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

4.png

话不多说，直接开始

安装

// 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

3.png

添加注释生成文档

1、学习 YAML 语言教程

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

上代码 get 方式

// 获取博客列表
/**
 * @swagger
 * /api/blog/list:
 *   get:
 *     summary: 获取博客列表
 *     description: 获取博客列表
 *     tags:
 *       - blogs
 *     parameters:
 *       - name: author
 *         in: query
 *         required: false
 *         description: 作者
 *         type: string
 *       - name: keyword
 *         in: query
 *         required: false
 *         description: 搜索关键字
 *         type: string
 *     responses:
 *       200:
 *         description: 成功获取
 */
router.get('/list', async (ctx, next) => {
  const query = ctx.query
  let author = query.author || ''
  const keyword = query.keyword || ''

  const listData = await getList(author, keyword)
  ctx.body = new SuccessModel(listData)
})

post需要模板添加注释，如果无法加载 definition ，需要查看自己安装的版本

/**
 * @swagger
 * definitions:
 *  loginparam:
 *    properties:
 *      username:
 *        type: "string"
 *        default: "shangsan"
 *        description: 用户名
 *      password:
 *        type: "string"
 *        default: "123"
 *        description: 密码
 */

/**
 * @swagger
 * /api/user/login:
 *   post:
 *     summary: 登录
 *     description: 登录
 *     tags:
 *       - user
 *     consumes:
 *      - application/json
 *      - application/xml
 *     produces:
 *      - application/json
 *      - application/xml
 *     parameters:
 *       - name: body
 *         in: body
 *         schema:
 *          $ref: '#/definitions/loginparam'
 *     responses:
 *       200:
 *         description: 发布成功
 *       402:
 *          description: 信息填写不全
 *       403:
 *          description: 参数类型错误
 */


router.post('/login', async (ctx, next) => {

如果觉得这样乱，注释都写在路由文件里面，可以单独摘出注释，单独写文件，我个人还是倾向于这样的方式，比较清晰，便于维护

上述配置完成后，访问localhost:8000/swagger，可能会一直转圈，访问不了，也可能会报错，如图

微信截图_20210813100220.png

很明显，相应的资源没有加载下来，cdn，时好时坏，那么就要把资源拿到本地：

所以就开始静态资源配置，找到相应资源为 koa2-swagger-ui 的 cdn 引用，将对应的资源拿到本地并配置修改：

微信截图_20210813101313.png

在 public 中新建文件为 swagger-ui ，将 图中几个文件放入文件夹中，在能访问时候将 cdn 文件拿下来，放入文件中，如图：

微信截图_20210813101700.png

这三个文件如果拿不到，可以私信我，一般每天早上会查看简书信息；
接下来修改 index.hbs 文件，把 cdn 文件换成本地文件地址就好了：

3333.png

然后修改 app.js 中的配置引用

// const { koaSwagger } = require('koa2-swagger-ui')
const { koaSwagger } = require('./public/swagger-ui')

然后保存，也可能需要重启项目，然后就可以访问了；

资源拿不到记得私信我；