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

一时失言乱红尘 2022-12-10 11:29 26阅读 0赞

大家好，我是[小佑@小佐：https://blog.csdn.net/Smell\_rookie][https_blog.csdn.net_Smell_rookie]，是一名页面仔工程师，我会不定时在CSDN更新我的博客，有兴趣的可以点个关注来逛逛我的主页  
前言：倘若是异地对接接口文档，有对接文档是非常必要的，经过对比我选用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

## 版本 ##

![在这里插入图片描述][20200926092213779.png_pic_center]

## 配置文档 ##

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

此时页面是这样的：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1NtZWxsX3Jvb2tpZQ_size_16_color_FFFFFF_t_70_pic_center]

## 接口注释 ##

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

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

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

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

[https_blog.csdn.net_Smell_rookie]: https://blog.csdn.net/Smell_rookie
[20200926092213779.png_pic_center]: /images/20221123/fe1c2e3e581c4725bd8f526b34c291b9.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1NtZWxsX3Jvb2tpZQ_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/a88aeb07117e4e01a062b7d65723e782.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1NtZWxsX3Jvb2tpZQ_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221123/93f809c5d027475e9a5517f010b1c3d8.png
[token]: https://blog.csdn.net/Smell_rookie/article/details/108708689
[Link 1]: https://blog.csdn.net/Smell_rookie/article/details/108886254