一 环境准备

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-jsdocrouter.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官方文档