同事的接口文档我每次看着就头大,毛病多多。。。(1)

简介: 同事的接口文档我每次看着就头大,毛病多多。。。(1)

前后端差点打起来


事情是这样的:今天我们公司的后端说他接口写完了,并分享了一个接口文档给我。用的就是 Swagger UI 自动生成的那种接口文档,就像这种:


1.png


这种 Swagger 文档我每次看着就头大,毛病多多:


查看多级模型时要一级级点开

在接口数量变多的时候非常难用,连分类菜单都没有

提交参数为 JSON 的时候不能格式化

参数出错的时候查找麻烦

返回结果不能折叠,长得没法看

时间比较紧急,我就按照他给的文档里的参数与响应数据,写到了我的前端页面上,前端这边简单自测了一下就匆匆上线了。


上线完当晚就炸了。。


页面上各种接口报错:


  • 参数不存在


  • 参数类型错误


  • 接口不存在(是因为接口写错了)


老大马上过来找我俩,但是前后端各执一词:


  • 前端:我吊你,怎么你分享的接口这么多错误?
  • 后端:我吊你,你用之前不会测一测接口正不正常?
  • 前端:我为什么要测?你开发的接口,你自己不测好?
  • 后端:我怎么知道你要用什么样的数据!你要是稍微测一下接口,能有这么多事?


2.png


归根结底是个成本问题


这时候老大很冷静,阻止了我们的吵架。


老大分析了一下这次事故的主要原因:


1、后端马虎了,一些接口没有写对,也忘记调试了

2、时间紧,前端没来得及完全测接口

然后老大说,这归根结底是个成本问题。要是前后端测接口都特别简单方便,你们这个问题就不存在了嘛!


你们现在用的在线接口文档,功能几乎为零。应该选一个功能更加强大的在线接口文档工具,直接在线就把接口调了,你们是不是就不会出这些问题了。


这个工具应该具备以下功能:


调试功能,前端能很方便地调试接口数据


代码生成功能,这样前端可以少写点代码,提高效率同时也提高了准确性

接口同步功能,接口文档一定要是最新的代码信息

我们纷纷点头,是啊是啊。


image.png


老大说,我最近试了一款工具,就可以零成本地解决你们这些问题!


然后他给我们看了一个神仙文档。


就是这个!!⬇️⬇️⬇️


4.png


为什么说它神仙呢?因为它满身都是牛逼到不行的特性,比平常见到那些 API 文档不知道高到哪里去了。


5.png


在线调试


这个文档是用 Apifox 做的,我之前有试用过这个工具,完全免费不限功能的,没想到最近又有这么多厉害的新功能出来了。


点击文档右上角的运行按钮,就会出现“在线运行”的模块


6.png


这个界面上就能直接调试接口了!直接 1. 填参数,2. 选环境,3. 点发送,接口请求就发出去了!下面就有返回结果!根本用不着 Postman!更不用把 API 照着抄一遍!


7.png


我心想,如果当时上线之前,用的是 Apifox 的话,那简直是不会出现事故:


参数不存在?我在线调试后获得数据了,通过比对我知道哪个参数不存在

参数类型错误?同样的,在线调试之后,通过比对,我知道哪个参数的类型是错的

接口不存在(是因为接口写错了)?调试的时候就报接口不存在了,第一时间找后端~


8.png


自动生成


我跟老大说,这个功能看起来是很强大啊。可是要是上线时间紧,谁有功夫去搞这么个接口文档啊,配置起来应该很麻烦吧?


老大邪魅一笑。


9.png


他说,这个文档,是自!动!生!成!的!


只要把 Swagger 的 URL 填到 Apifox 里面去,Apifox 就会自动导入 API 定义,然后就能生成这个好用的文档!


后端随便改代码,前端随时可以在线调试!


10.png


而且,还可以导入多个来源的 Swagger!一套接口文档来自多个不同的后端项目也没问题!


11.png


生成请求代码


后端说,不就是一个在线调试接口吗,也没有到神仙的地步嘛。


老大说,你还是太年轻。


12.png


在这个在线文档页面上,还有一行熟悉的 icon。这是什么呢?


13.png


自!动!生!成!代!码!


点击对应的语言,就能直接生成请求的代码!???


我选择了 JavaScript 之后,居然还提供了 Fetch、Axios、Jquery 等等请求方式的代码???


14.png


我直接 copy 一下代码,粘进代码里就能用???


一个在线文档,卷成这样至于嘛???


15.png


生成模型代码


老大说,别急,还没完。


16.png


API 文档嘛,都会有个“返回响应”的模块,就是告诉你后端吐出来的数据是什么类型什么长度等等。前端再写个数据结构把这些数据接着,然后放进页面里去。


在这个神仙文档里呢,“返回响应”里也有个“生成代码”。


17.png


我点了一下,就弹出了这个框:


18.png


左边还可以选择你生成代码的配置,包括:编程语言、命名风格、校验开启等等。


我看了看,Java,C,C++,JS,Swift,Go,Python,TypeScript……基本上我知道的语言全都有。


怎么着?返回数据结构的代码也不用写了?复制一下粘过去就行了?


我默默翻了翻它自动生成的代码,又关上了。


我感觉我自己写的 Java 代码还没它自动生成写的好。


19.png

相关文章
终于搞明白什么叫做回调了
终于搞明白什么叫做回调了
58 0
|
监控 Java 关系型数据库
让我干一遍也就罢了,居然还一次次的要我给你,当我好欺负吗?
让我干一遍也就罢了,居然还一次次的要我给你,当我好欺负吗?
149 0
|
前端开发 测试技术 API
同事的接口文档我每次看着就头大,毛病多多。。。(2)
同事的接口文档我每次看着就头大,毛病多多。。。(2)
123 0
同事的接口文档我每次看着就头大,毛病多多。。。(2)
|
消息中间件 存储 前端开发
面试官让我手写队列,差点没写出来,回来后赶忙把重点记下来
栈和队列是一对好兄弟,前面我们介绍过一篇栈的文章(栈,不就后进先出),栈的机制相对简单,后入先出,就像进入一个狭小的山洞,山洞只有一个出入口,只能后进先出(在外面的先出去,堵在里面先进去的就有点倒霉)。而队列就好比是一个隧道,后面的人跟着前面走,前面人先出去(先入先出)。日常的排队就是队列运转形式的一个描述!
112 0
面试官让我手写队列,差点没写出来,回来后赶忙把重点记下来
|
Java 中间件 程序员
最网最全bug定位套路,遇见bug再也不慌了
最网最全bug定位套路,遇见bug再也不慌了
320 0
|
芯片
程序人生 - 手上总有静电该怎么处理?
程序人生 - 手上总有静电该怎么处理?
146 0
程序人生 - 手上总有静电该怎么处理?
|
XML JSON API
扔掉 Postman ? 这个调接口神器更有效率
扔掉 Postman ? 这个调接口神器更有效率
169 0
扔掉 Postman ? 这个调接口神器更有效率
|
算法 Java
别在网上乱找代码了,找了一段代码突然爆了!!!
本人是做游戏服务器开发的,碰到一个需求,给符某些要求的玩家的发送道具奖励,奖励的数量根据离线的天数计算。 这个需求实现起来很简单,只需要在玩家上线的时候计算上次离线时间和当前时间间隔的天数,然后根据策划的算法,计算出道具种类与数量,发一封邮件给玩家就可以了。
|
架构师 算法 Java
不要网上乱拷贝代码了!一段网上找的代码把公司服务器崩了!
碰到一个需求,给服某些要求的玩家的发送道具奖励,奖励的数量根据离线的天数计算。这个需求实现起来很简单,只需要在玩家上线的时候计算上次离线时间和当前时间间隔的天数,然后根据策划的算法,计算出道具种类与数量,发一封邮件给玩家就可以了。
|
Web App开发 新零售 移动开发