当Swagger遇上YApi，瞬间高大上了！

Swagger 经常被人吐槽界面不够好看、功能不够强大，其实有很多工具可以和 Swagger 结合使用，结合之后就会变得非常好用。之前写过一篇文章《Swagger 界面丑、功能弱怎么破？用 Postman 增强下就给力了！》，有朋友留言说 YApi 也很好用。最近体验了一把 YApi，发现确实不错，推荐给大家！

YApi 简介

YApi 是高效、易用、功能强大的 API 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。YApi 在 Github 上已累计获得了 18K+Star，具有优秀的交互体验，YApi 不仅提供了常用的接口管理功能，还提供了权限管理、Mock 数据、Swagger 数据导入等功能，总之功能很强大！

安装

环境准备

本地部署 YApi 需要先安装 nodejs 和 MongoDB，我们先把它们安装好。

• 安装 nodejs，直接下载安装包双击安装即可，这里安装的是12.14.0版本，下载地址：https://nodejs.org/dist/v12.14.0/node-v12.14.0-x64.msi;

• 安装 MongoDB，参考《MongoDB 快速入门，掌握这些刚刚好！》中的安装即可，这里安装的是4.2.5版本。

安装 yapi-cli

yapi-cli是 YApi 官方提供的安装工具，可以通过可视化界面来部署 YApi 服务，非常方便！

• 使用 npm 命令来安装yapi-cli：

npm install -g yapi-cli --registry https://registry.npm.taobao.org

• 安装成功后控制台输出如下内容；

• 安装成功后使用yapi server命令来启动 YApi 的可视化部署界面。

yapi server

安装 YApi

• 通过可视化部署界面安装 YApi 服务，访问地址：http://localhost:9090

• 安装完成后会输出如下信息，提示 YApi 的默认管理员账号密码及访问地址；

• 进入 YApi 的安装目录，使用 node 命令启动 YApi 服务：

node vendors/server/app.js

• 启动成功后控制台输出信息如下；

• 通过页面访问 Yapi，默认账号密码为admin@admin.com:ymfe.org，访问地址：http://localhost:3000

使用

从 Swagger 导入数据

• 使用管理员账号登录成功后，先创建一个mall-tiny-group分组；

• 创建分组成功后，在该分组下点击创建项目，添加mall-tiny-swagger项目；

• 之后启动我们之前的mall-tiny-swagger项目，启动成功后 Swagger 接口文档访问地址：http://localhost:8088/swagger-ui/

• 选择好 YApi 的数据管理功能，配置好 Swagger 的 api-docs 路径，然后进行数据导入；

• 至此 Swagger 中的 API 接口已成功导入到 YApi，点击接口标签查看所有导入接口。

接口管理

• 打开添加商品的接口看看，可以看到非常完善的接口文档信息，注释都有了；

• 来试试接口运行功能，我们会发现默认的接口请求地址并不符合我们的要求，需要在环境配置中设置；

• 由于是跨域请求，Chrome 浏览器需要安装跨域请求插件，下载地址：https://github.com/YMFE/cross-request/archive/master.zip

• 由于我们的部分接口在请求头中添加 token 才能访问，所以我们先调用登录接口获取 token；

• 之后在设置->环境配置中添加 Authorization 头；

• 再次调用需要登录的接口，可以正常获取到数据，返回数据虽然格式化了，但是没有折叠功能，数据太长的话就不太好看了；

Mock 功能

• 在我们调用 POST 接口提交 JSON 数据时，默认 Mock 的 JSON 数据有点不太符合我们的要求；

• 可以通过接口信息中的编辑->高级设置进行修改；

• 我们可以发现每一个接口信息中都有个 Mock 地址，当我们后台接口已经定义好格式，但是没有实现时，前端可以使用该地址来 Mock 数据进行调试；

• 调用 Mock 地址可以获取到一些测试数据，数据取值返回可以通过上面的 Mock 设置自行修改；

从 Swagger 自动同步

• 当我们的接口修改了，API 文档如何同步呢，我们可以通过设置->Swagger自动同步来开启自动同步功能，有三种数据同步模式可以选择；

权限管理

如果有新的成员加入进来，需要查看 API 文档怎么办？

• 首先可以通过注册界面注册一个成员账号，此处账号为test@qq.com:123456；

• 之后使用管理员账号登录，然后通过成员列表->添加成员，将用户添加到相应分组；

• 最后使用成员账号登录即可访问相应 API 文档了。

总结

YApi 结合 Swagger 使用果然很强大！之前使用 Postman 结合 Swagger 使用时，文档查看、自动同步的问题都得到了解决，为了保证我们 API 文档访问的安全性还提供了权限管理功能。当 API 数据格式定义好后，Mock 功能让前端无需后台实现也可以调试接口。不过对于 JSON 格式支持有点偏弱，要是能对 JSON 数据进行折叠显示就更好了！

参考资料

官方文档：https://hellosean1025.github.io/yapi/documents/index.html

项目源码：https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-swagger