[记录五]Vue+node+koa2+mysql+nginx+redis，全栈开发小程序和管理员管理系统项目——使用swagger自动生成接口文档

因为我们是异地对接接口文档，为此有对接文档是非常必要的，经过对比我选用swagger，但是node使用swagger有很多坑（细节）需要注意，我花费了两天时间才将文档展现出来，尤其是对注释部分需要严格按照格式去写。
我这里选用swagger-jsdoc和koa2-swagger-ui去实现。
首先我们在routes文件夹中另起一个文件swagger.js，为什么在routes文件下呢？因为在给到别人看文档的时候你是打开127.0.0.1:300/swaggger这样的网址的，所以它相当于node的其中一个路由。

下载依赖

npm install swagger-jsdoc koa2-swagger-ui

或

yarn add swagger-jsdoc koa2-swagger-ui

版本

配置文档

//swagger.js
const router = require('koa-router')()
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerDefinition = {
     
  info: {
     
    title: '你的文档标题',
    version: '1.0.0',
    description: '你的文档说明'
  },
  securityDefinitions: {
     
    ApiKeyAuth: {
     
      type: 'apiKey', // 类型
      in: 'header', // 位置
      name: 'token' // 参数
    }
  },
  host: '127.0.0.1:300',//需要跟你node服务器地址一样
  basePath: '/' // Base path (optional)
};
const options = {
     
  swaggerDefinition,
  apis: ['./routes/*.js'] // 写有注解的router的存放地址
};
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文件引入路由

//app.js
const koaSwagger = require('koa2-swagger-ui')

//swagger配置
app.use(//注意这里需要看koa2-swagger-ui的版本 不然会报koaSwagger不是一个函数等错误
  koaSwagger({
     
    routePrefix: '/swagger', // host at /swagger instead of default /docs
    swaggerOptions: {
     
      url: '/swagger.json' // example path to json
    }
  })
)

此时页面是这样的：

接口注释

要想接口的路径和参数等信息出现在127.0.0.1:300/swagger页面上，需要在接口那协商注释；
swagger的注释是以@swagger开头的，方便swagger识别：下面以管理员接口为栗子。

//admin.js
// #region 
// #region可以将注释代码收缩
/**
 * @swagger
 * /admin/userLogin:
 *   post:
 *     summary: 管理员登录
 *     description: 管理员登录
 *     tags:
 *       - 管理员模块
 *     parameters:
 *       - name: name
 *         in: query
 *         required: true
 *         description: 账号
 *         type: string
 *       - name: password
 *         in: query
 *         required: true
 *         description: 密码
 *         type: string
 *     responses:
 *       200:
 *         description: 成功获取
 *         schema:
 *           type: 'object'
 *           properties:
 *             code:
 *               type: 'number'
 *             data:
 *               type: 'object'
 *               description: 返回数据
 *             message:
 *               type: 'string'
 *               description: 消息提示
 */
// #endregion

这样一个比较完整的接口文档就出来了。页面上也会出现如下：

这样就可以将自己的接口文档输出到页面上了。下篇将介绍前端请求上传图片和显示图片服务端需要做什么操作。

上一篇：token控制接口权限
下一篇：服务端图片上传与下载