新来的后端整的接口文档看着真不优雅!
共 3193字,需浏览 7分钟
· 2022-06-21
事情是这样的:今天我们公司的后端说他接口写完了,并分享了一个接口文档给我。用的就是 Swagger UI 自动生成的那种接口文档,就像这种:
![](https://filescdn.proginn.com/b7e84c5ed169c0be70683e6f988e3afe/c319de54146f7a0420b2b282648af031.webp)
这种 Swagger UI文档我每次看着就头大,毛病多多
查看多级模型时要一级级点开 在接口数量变多的时候非常难用,连分类菜单都没有 提交参数为 JSON 的时候不能格式化 参数出错的时候查找麻烦 返回结果不能折叠,长得没法看
时间比较紧急,我就按照他给的文档里的参数与响应数据,写到了我的前端页面上,前端这边简单自测了一下就匆匆上线了。
上线完当晚就炸了。。
![](https://filescdn.proginn.com/5de6f7e4ece10efc282ecc5345e525ac/dbc567c6f7d9b68f5dd2e0e912ce2345.webp)
页面上各种接口报错:
参数不存在 参数类型错误 接口不存在(是因为接口写错了)
老大马上过来找我俩,但是前后端各执一词:
前端:我吊你,怎么你分享的接口这么多错误? 后端:我吊你,你用之前不会测一测接口正不正常? 前端:我为什么要测?你开发的接口,你自己不测好? 后端:我怎么知道你要用什么样的数据!你要是稍微测一下接口,能有这么多事?
![](https://filescdn.proginn.com/5860d05aeda4f4375a1d0499fee60fd2/aae6421d00292f71d5f6889c3750902b.webp)
归根结底是个成本问题
这时候老大很冷静,阻止了我们的吵架。
![](https://filescdn.proginn.com/1cfefb28cb41410e9d7cdc312f5ff6f4/a49589cbe7f9cd8cdda9a1fa4bbd1014.webp)
老大分析了一下这次事故的主要原因:
1、后端马虎了,一些接口没有写对,也忘记调试了 2、时间紧,前端没来得及完全测接口
然后老大说,这归根结底是个成本问题。要是前后端测接口都特别简单方便,你们这个问题就不存在了嘛!
你们现在用的在线接口文档,功能几乎为零。应该选一个功能更加强大的在线接口文档工具,直接在线就把接口调了,你们是不是就不会出这些问题了。
这个工具应该具备以下功能:
调试功能,前端能很方便地调试接口数据 代码生成功能,这样前端可以少写点代码,提高效率同时也提高了准确性 接口同步功能,接口文档一定要是最新的代码信息
我们纷纷点头,是啊是啊。
![](https://filescdn.proginn.com/27dcb2a1f823136b6b1e761bfded515f/8dcc10fbaf27fe02b64741305e269137.webp)
老大说,我最近试了一款工具,就可以零成本地解决你们这些问题!
然后他给我们看了一个神仙文档。
就是这个!!⬇️⬇️⬇️
![](https://filescdn.proginn.com/d5075972f8f0901368eac60d9a818a5a/b48a34c98b1b5d14c9e466e03f8bdf84.webp)
为什么说它神仙呢?因为它满身都是牛逼到不行的特性,比平常见到那些 API 文档不知道高到哪里去了。
![](https://filescdn.proginn.com/558afad8a1b2eada86b0e1054addc394/d0d1613fdd256df6fc8e6d9fcee80908.webp)
在线调试
这个文档是用 Apifox 做的,我之前有试用过这个工具,完全免费不限功能的,没想到最近又有这么多厉害的新功能出来了。
点击文档右上角的运行按钮,就会出现“在线运行”的模块
![](https://filescdn.proginn.com/8a3ad418e227229bedc01931b6f067db/0c98e4045f38928d474e72b9e7b5e523.webp)
这个界面上就能直接调试接口了!直接 1. 填参数,2. 选环境,3. 点发送,接口请求就发出去了!下面就有返回结果!根本用不着 Postman!更不用把 API 照着抄一遍!
![](https://filescdn.proginn.com/193589880e06e1f035f4fc674618b41c/8536a313c9a06a30223541f78ba8b945.webp)
我心想,如果当时上线之前,用的是 Apifox 的话,那简直是不会出现事故:
参数不存在?我在线调试后获得数据了,通过比对我知道哪个参数不存在 参数类型错误?同样的,在线调试之后,通过比对,我知道哪个参数的类型是错的 接口不存在(是因为接口写错了)?调试的时候就报接口不存在了,第一时间找后端~
![](https://filescdn.proginn.com/c3a112f42cbf254b7646a99032951d81/951033caa17505e99210c79941e9bc97.webp)
自动生成
我跟老大说,这个功能看起来是很强大啊。可是要是上线时间紧,谁有功夫去搞这么个接口文档啊,配置起来应该很麻烦吧?
老大邪魅一笑。
![](https://filescdn.proginn.com/5510b0d4be2f2fb4f74a99c9c299ce3b/dcd21a95dc96a293a158d0085e6b5348.webp)
他说,这个文档,是自!动!生!成!的!
只要把 Swagger 的 URL 填到 Apifox 里面去,Apifox 就会自动导入 API 定义,然后就能生成这个好用的文档!
后端随便改代码,前端随时可以在线调试!
![](https://filescdn.proginn.com/ad77522fc11abe5f826ffc9e53385a72/0c06bfe43785ae6d3a27f6f83cf50a98.webp)
而且,还可以导入多个来源的 Swagger!一套接口文档来自多个不同的后端项目也没问题!
![](https://filescdn.proginn.com/c19a3a1f4be7d5af4ab564b85fa86587/b85c259abcd87d8bc3cf46a3955da581.webp)
生成请求代码
后端说,不就是一个在线调试接口吗,也没有到神仙的地步嘛。
老大说,你还是太年轻。
![](https://filescdn.proginn.com/b89a90aa849195ef7c693ca965fbd1da/3db05bc53954ed1e13c073cdf3724d8a.webp)
在这个在线文档页面上,还有一行熟悉的 icon。这是什么呢?
![](https://filescdn.proginn.com/2cedf32cb342499d8818390e9e768126/770654b30b18d07fe5c655aa09ce6677.webp)
自!动!生!成!代!码!
点击对应的语言,就能直接生成请求的代码!???
我选择了 JavaScript 之后,居然还提供了 Fetch、Axios、Jquery 等等请求方式的代码???
![](https://filescdn.proginn.com/04fff98f1c23158bc791a3f77c52bd9e/05d71e759be12fe69aa20e89daa60712.webp)
我直接 copy 一下代码,粘进代码里就能用???
一个在线文档,卷成这样至于嘛???
![](https://filescdn.proginn.com/554eed1a111e72da0303597d69f1bffa/b04a7d20a0be9ab20ceb4d623bd7e680.webp)
生成模型代码
老大说,别急,还没完。
![](https://filescdn.proginn.com/63b98cd598bce944075f9dd8fa0ba69f/c5e95a7bc0ba0fdea76fc056cdae2f73.webp)
API 文档嘛,都会有个“返回响应”的模块,就是告诉你后端吐出来的数据是什么类型什么长度等等。前端再写个数据结构把这些数据接着,然后放进页面里去。
在这个神仙文档里呢,“返回响应”里也有个“生成代码”。
![](https://filescdn.proginn.com/313ab418b80edfc61288c956ec163c8f/87dc98adb593382eecb87f0e849d2784.webp)
我点了一下,就弹出了这个框:
![](https://filescdn.proginn.com/19e2e30d9056bd2ff8d45ae8395c5e4a/02caef6add71bc541d2967011b6635b9.webp)
左边还可以选择你生成代码的配置,包括:编程语言、命名风格、校验开启等等。
我看了看,Java,C,C++,JS,Swift,Go,Python,TypeScript……基本上我知道的语言全都有。
怎么着?返回数据结构的代码也不用写了?复制一下粘过去就行了?
我默默翻了翻它自动生成的代码,又关上了。
我感觉我自己写的 Java 代码还没它自动生成写的好。
![](https://filescdn.proginn.com/e3be5e9f9a91991f9a8dcf1a7195bd12/02b6a914164f614930576900a03d927a.webp)
云端 Mock
我说老大,我明白了。我这就去下载 Apifox,下个迭代我就用这个在线文档。哦不,下个迭代我就逼后端用这个在线文档。
老大说,急什么。等我说完。你知道云端 Mock 吗?
我说,云嘛,神仙都是要驾云的,这很正常。
老大说你正常一点。云端 Mock,就是在 API 文档页面上就直接实现 Mock 服务,虚拟一个服务端出来。
我:???
![](https://filescdn.proginn.com/df4deeaecfe68578ab3c942d6a855c76/2e66be568f4741b27fd273db9f4f56d8.webp)
老大说,比如,我们要请求一个银行的 API,银行肯定不会让你随便请求啊,都是要验证身份限制次数的。用这个 Apifox 呢,你就可以直接在接口文档上请求 Mock 数据了,也不会限制你的次数,也不会收你的钱。
我说老大,咱们是不是跳得有点快。你驾云我跟不上的。
老大说没有啊,我们不是在聊这个在线文档的特性嘛。你看,这里有测试环境、正式环境和云端 Mock 环境,你只要切换到云端 Mock 环境,请求就会发给 Mock 服务器了,跟正式环境调试一样一样的。
![](https://filescdn.proginn.com/7d7dc90307fdb1993ac3481a0974a784/a83c6720928f883d3b8d42ce24132e44.webp)
我:!!!!!
还可以这样??
老大又用浏览器打开了这个 URL(https://mock.apifox.cn/m1/1035644-0-default/users/2),说你看,直接访问 URL 就能获取到 Mock 数据了,你们前端用起来是不是很爽?
![](https://filescdn.proginn.com/1b1e56836c2bc45f81cb88cc2ccf4e7f/abc95f4864363a9f6439b2d1da0c0cf2.webp)
我猛点头。
![](https://filescdn.proginn.com/17562da32f15f478f2d401534ac4558d/0465a6046d4929d5dc0149ac192d275d.webp)
这个时候,后端说,那是不是我们直接把常用的那些第三方 API 都做成这种能云端 Mock 的 API 文档,然后开发就都能直接调试第三方接口了?连 Mock 服务器都不用架?
我:
![](https://filescdn.proginn.com/14e0012bf2b6903b3363826503edc9d0/e7864963a0be8092251d414e7c14fca7.webp)
API Hub
老大说,你们啊,too young too simple,sometimes naive.
给你们看个东西。
![](https://filescdn.proginn.com/4f68d5fc9e76f23196168f1d51dda1a7/049eaf1cb5653fa87eb9e0f5295d7bec.webp)
这个,叫做 API Hub。
![](https://filescdn.proginn.com/327483bfa55f2e36ada0470419c496d5/cf0fa9ff25fc111e2d202d742df21016.webp)
在 Apifox 里面,已经把这些最常用的第三方 API 都做好了!即时通讯的,电商的,查快递的,项目管理的,统统都有!每一个都可以在线运行!生成代码!也可以克隆到自己的项目里,然后用云端 Mock!
![](https://filescdn.proginn.com/54a164c0a65f417be57d8a7c24d121a6/3ac3efad24ea8b04428dd27e6dbb23f0.webp)
老大说,人家都把接口文档公开出来了,你们也好好学学人家大厂的接口是怎么设计的。哦对了,咱们公司有接口要公开出去的话,也可以发布到这个 API Hub。
![](https://filescdn.proginn.com/5cd4f3b015936d27f6c3665afee6a4a4/50c4c7ee19095e76c88a3cc4c72d8e68.webp)
老大说,好了,我说完了。你们都听懂了吗?
我说,懂了,明天就去跟后端对线。
![](https://filescdn.proginn.com/78bbf3f4409e6c205748ab4e4a2038f1/c75a1f71c945d2b106e8163e2838a40f.webp)
后端说,等什么明天!我现在就要!
Apifox
最后,老大语重心长地说,年轻人啊,还是要多学学先进技术和工具。
Apifox = Postman + Swagger + Mock + JMeter。集接口文档工具、接口 Mock 工具、接口自动化测试工具、接口调试工具于一体,提升 10 倍研发效率。
![](https://filescdn.proginn.com/cc38c261c6553eafd9c76c1f4870a229/3909ffea1464dd3f56eebbe93594fb6c.webp)
在这些核心功能之外,Apifox 还提供了大量创新的围绕 API 的扩展特性,适合各种规模的开发团队使用。
![](https://filescdn.proginn.com/38f63979e89546fa610424b7e8a55632/fc2eb6f67700a2030b9d08b60ae8f38b.webp)
而且我看他们官方还有预告,后续会支持更强大的文档功能,包括自定义域名、自定义导航、多主题样式选择、自定义 css、自定义页面等等等等,你们都要关注一下。
要是使用过程中有问题的话,还可以加入 Apifox 用户群提问和学习。
赶紧点击“阅读原文”去下载吧
下载链接:http://apifox.cn/a1guide1
或者,复制上面链接,去官网下载吧
![](https://filescdn.proginn.com/2de2b2eb6ca3a010e902d6af7a396ffe/558945d6e7fb086279e17d7a6c64eac5.webp)