天天看点

[记录五]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
           

版本

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

配置文档

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

           

此时页面是这样的:

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

接口注释

要想接口的路径和参数等信息出现在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

           

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

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

这样就可以将自己的接口文档输出到页面上了。下篇将介绍如何让远在他方的小伙伴调用本地的服务。

上一篇:token控制接口权限

下一篇:服务端图片上传和下载

继续阅读