五 Koa2项目中使用Swagger

一 环境准备

1.首先需要先安装koa2-swagger-ui，以及swagger-jsdoc
2.官方文档：Swagger官方文档

npm install koa2-swagger-ui  //
npm install swagger-jsdoc

二 使用swagger

1.在app.js文件中引入koa2-swagger-ui，并设置swagger的基本配置

const { koaSwagger } = require('koa2-swagger-ui');
app.use(
  koaSwagger({
    routePrefix: '/swagger/index.html', // 这里配置swagger的访问路径
    swaggerOptions: {
      url: '/swagger/swagger.json', // 这里配置swagger的文档配置URL，也就是说，我们展示的API都是通过这个接口生成的。
    },
  }),
);

2.在routes文件夹下创建一个swagger.js的路由文件，然后将这个路由文件应用到app.js中
3.在swagger.js文件中编写一下内容

const router = require('koa-router')()
const path = require('path')
const swaggerJSDoc = require('swagger-jsdoc')  //引入swagger-jsdoc

router.prefix('/swagger')  //设置路由，与app.js中的路由配置保持一致
const swaggerDefinition = {
    info: {
        title: 'Test API',        //文档标题
        version: 'v1',            //版本号
        host: 'localhost:3001',   //服务器地址
        basePath: '/'             //访问地址，有些人喜欢在host:port/api/xxx这种格式，可以在此处配置为/api/.
    }
}
const options = {
    swaggerDefinition,
    //写有注解的router的存放地址, 最好使用path.join(),这里使用物理路径
    apis: [
        path.join(__dirname, "./xxx.js"),
        path.join(__dirname, "./xxx1.js"),
    ]
}
const swaggerSpec = swaggerJSDoc(options)

// 通过路由获取生成的注解文件
router.get('/swagger.json', async function (ctx) {
    ctx.set('Content-Type', 'application/json')
    ctx.body = swaggerSpec
})
module.exports = router

配置完成之后，可以访问http://localhost:3001/swagger/index.html,即可以看到我们的swagger-ui界面。

三 显示接口

1.当swagger-ui可以正常显示以后，就可以配置接口信息了，接口的显示是通过添加注解实现的，在接口的头部添加相关注解就可以将接口显示在swagger-ui中了。
以下是我写的一个新增管理员的注解，注意缩进和空格，缩进和空格错了会导致这个接口无法正常显示

/**
 * @swagger
 * /system_manager/add:
 *    post:
 *      tags:
 *      - system_manager
 *      summary: 新增管理员信息
 *      consumes:
 *        - application/json
 *      parameters:
 *      - name: system_manager
 *        in: body
 *        description: 新增管理员信息
 *        schema:
 *          type: object
 *          required:
 *            - id
 *            - account
 *            - token
 *          properties:
 *            obj:
 *              type: object
 *              required:
 *                - account
 *                - name
 *                - phone
 *                - roleId
 *                - state
 *              description: 新增数据对象
 *              properties:
 *                name:
 *                  type: string
 *                  description: 管理员姓名  
 *                account:
 *                  type: string
 *                  description: 管理员账号
 *                state:
 *                  type: integer
 *                  description: 账号状态    
 *                phone:
 *                  type: string
 *                  description: 管理员联系方式   
 *                roleId:
 *                  type: integer
 *                  description: 管理员角色编码      
 *            account:
 *              type: string
 *              description: 当前登录用户账号
 *            token:
 *              type: string
 *              description: 当前登录用户Token
 *      responses:
 *        200:
 *          description: successful operation
 * */

根据设置，可以点击Model按钮查看注解。

注解的设置较多，但是功能很完善，具体请参考官方文档Swagger官方文档