作为前端开发者我们该如何高效的利用Swagger-ui

1,875 阅读5分钟

导语

相信作为一名前端开发人员大家对于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替换

image.png

这里先跳过实现思路,直接上效果(思路放在最后面,感兴趣的童鞋可以自行查阅)先上一波 效果图

效果图

接口数据展示(对比原生Swagger-ui页面,是不是感觉每个字段都得到了前所未有的重视,毕竟每个字段都是一条小生命~)

image.png

点击 更多 服务器配置可以保存多个swagger地址

image.png

接口路径与接口名称模糊搜索

image.png

Request Body / Response Body 预览

image.png

再来个特写!支持树级结构预览,支持各个层级单独生成代码

image.png

接下来是代码生成: Vue

image.png

JavaScript

image.png

Flutter Dart

image.png

对于代码生成就展示这么多

敲黑板,划重点,看这里

所有代码生成都可以自由配置,例如上面没有展示生成React代码,你完全可以使用代码模板配置功能,配置出一份你想要的React代码,所有语言通用!!!

下面再展示一下强大的模板语法配置

image.png

你只需要写好代码模板,一切的操作都交给生成器,具体的模板语法可以查看项目内的README.md文件

项目地址

好了,看到这里我相信你对swagger-ui-replace工具的功能都有所了解,下面是该项目的项目地址(开发不易,希望用到的童鞋能够给个star,感激不尽!)

线上开箱即用地址

还没完呢?

使用上面的开源项目,拉取下来需要在本地运行,嗯额,好家伙,真够麻烦的,每次使用还需要本地运行一下项目,这种重复且无意义的工作不应该在我们程序员生活里出现。

基于上述问题,博主搬出了自己省吃俭用 倾家荡产重金(9.9/月)买来的服务器,将项目已打包运行在服务器上,大家可以直接使用线上地址(支持跨域解决,支持https哦)

关于线上项目跨域:这里为了最方便的解决跨域问题,swagger-ui-replace工具会优先使用本地请求,发现跨域的情况下,会使用node服务器做一层中转,完美解决了前后端跨域问题。

好了

实现思路总结

关于数据

打开我们的Swagger-ui F12可以看到,Swagger-ui 网站请求一个api-docs接口

image.png

查看该接口返回内容可以看出,该接口返回了当前Swagger当前 项目 下的所有接口数

关于代码生成

这个项目最难的无非就是代码生成,博主当时接触到的有JavaScript项目,也有TypeScript项目,还有现在Flutter项目,那么如何能做到多端通用呢? 那既然要做到多端通用,为何不直接让用户自己配置代码模板呢,但是问题又来了,如何能做到让用户自己配置模板,我能根据用户的模板进行代码生成呢?基于此想法,博主第一时间想到了echarts,在使用echarts的过程中,有些地方为了提高灵活性和扩展性,官方会提供了一些api,使用指定变量代替用户想要展示的内容以达到动态使用的效果!这种方式用在此项目,绝!!!


文章到此结束,记录一下整个项目从0到诞生过程,我们实际开发过程中其实还有很多值得我们去创造的点,多点想法,反复琢磨,一切为了更加高效的写代码!

欢迎大家在下面评论探讨对于该项目的一些想法或提出不足,我会第一时间回复

—— end ——