导语
相信作为一名前端开发人员大家对于
Swagger-ui
并不陌生,作为前后端接口联调的API文档,我们几乎每天都在使用它,Swagger-ui
工具为我们带来了太多便利
BUT、BUT、BUT
正所谓"天下物无全美",再完美的东西也会有缺点
作为一名对于开发 效率 有着极大追求的的前端开发人员,怎能不给它找点茬
发现问题
-
查找接口 费时费力
-
场景1:后端发给我们某个接口,需要新增一些字段,我们需要先知道该接口的controller,接着需要在controller层下翻找到该接口。
-
场景2:公司人员流动大,新人接手维护该项目时,对于某些接口字段的改动,需要根据接口路径去查找对应的controller与接口。
-
-
Request/Response参数众多,手动复制粘贴,劳心费力
-
场景:对于新接口的联调,前端需要复制后端的json串作为前端请求参数,如果需要给每个参数加上注释(毕竟都是有追求的前端人,自然要考虑到后人接手时的可阅读性),一顿
ctrl
+c
ctrl
+v
,这也就算了,后端一旦更改某些字段,哭唧唧~~~
-
-
安卓/IOS/Flutter开发,使用第三方的jsonToEntity工具,可控性太差
- 场景:
Flutter
开发项目时,使用jsonToDart
生成实体时,需要先从swagger复制json,接着在idea工具内使用插件转换,转换后的代码完全由jsonToDart开发者决定,无法自定义,可控性太差。 - 补充:其实
JavaScript
TypeScript
等等前端语言开发项目时都会存在上面的问题。
- 场景:
-
项目开发阶段,需要联调的Swagger-ui地址众多,无法集中管理
-
场景:这相信大家都有所感受,无需多言。
目前困扰我的就这么多,不知道其他小伙伴有没有遇到什么问题,欢迎在评论区留言补充。
-
解决问题
作为一名有 追求 的前端开发者,岂能被这些小问题所困扰?
基于上述问题,博主利用 休息(摸鱼) 时间,打造了一款专属于前端开发人员用于替换Swagger-ui的高可用工具
swagger-ui-replace
名字是不是一看就懂,Swagger-ui替换
这里先跳过实现思路,直接上效果(思路放在最后面,感兴趣的童鞋可以自行查阅)先上一波 效果图
效果图
接口数据展示(对比原生Swagger-ui页面,是不是感觉每个字段都得到了前所未有的重视,毕竟每个字段都是一条小生命~)
点击
更多
服务器配置
可以保存多个swagger地址
接口路径与接口名称模糊搜索
Request Body / Response Body 预览
再来个特写!支持树级结构预览,支持各个层级单独生成代码
接下来是代码生成: Vue
JavaScript
Flutter Dart
对于代码生成就展示这么多
敲黑板,划重点,看这里
所有代码生成都可以自由配置,例如上面没有展示生成React代码,你完全可以使用代码模板配置功能,配置出一份你想要的React代码,所有语言通用!!!
下面再展示一下强大的模板语法配置
你只需要写好代码模板,一切的操作都交给生成器,具体的模板语法可以查看项目内的README.md文件
项目地址
好了,看到这里我相信你对swagger-ui-replace工具的功能都有所了解,下面是该项目的项目地址(开发不易,希望用到的童鞋能够给个star,感激不尽!)
- gitee:gitee.com/XieTS/swagg…
- github:github.com/xietianshen…
线上开箱即用地址
还没完呢?
使用上面的开源项目,拉取下来需要在本地运行,嗯额,好家伙,真够麻烦的,每次使用还需要本地运行一下项目,这种重复且无意义的工作不应该在我们程序员生活里出现。
基于上述问题,博主搬出了自己省吃俭用 倾家荡产 花重金(9.9/月)买来的服务器,将项目已打包运行在服务器上,大家可以直接使用线上地址(支持跨域解决,支持https哦)
关于线上项目跨域:这里为了最方便的解决跨域问题,swagger-ui-replace工具会优先使用本地请求,发现跨域的情况下,会使用node服务器做一层中转,完美解决了前后端跨域问题。
好了
实现思路总结
关于数据
打开我们的Swagger-ui
F12
可以看到,Swagger-ui
网站请求一个api-docs
接口
查看该接口返回内容可以看出,该接口返回了当前Swagger
当前 项目 下的所有接口数
关于代码生成
这个项目最难的无非就是代码生成,博主当时接触到的有JavaScript
项目,也有TypeScript
项目,还有现在Flutter
项目,那么如何能做到多端通用呢?
那既然要做到多端通用,为何不直接让用户自己配置代码模板呢,但是问题又来了,如何能做到让用户自己配置模板,我能根据用户的模板进行代码生成呢?基于此想法,博主第一时间想到了echarts,在使用echarts的过程中,有些地方为了提高灵活性和扩展性,官方会提供了一些api,使用指定变量代替用户想要展示的内容以达到动态使用的效果!这种方式用在此项目,绝!!!
文章到此结束,记录一下整个项目从0到诞生过程,我们实际开发过程中其实还有很多值得我们去创造的点,多点想法,反复琢磨,一切为了更加高效的写代码!
欢迎大家在下面评论探讨对于该项目的一些想法或提出不足,我会第一时间回复
—— end ——