接口文档进化图鉴,有些古早接口文档工具,你可能都没用过

LiamH · · 707 次点击 · · 开始浏览    

可能现在的小程序员听到以前还有人用过 word 来做接口文档,会惊讶得不行,但在前后端分离推行的早期,确实没有那么多趁手好用的接口文档工具。 互联网发展到现在,接口文档也经历了从简单的word到markdown,到swagger,到Apifox 等逐步进化的方式,变得越来越美观,越来越规范,也支持越来越多的功能辅助调试。 接下来给大家盘点一下这些年接口文档的进化历程。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/aa0ddd6a5c7048dca75d8767985a3efb~tplv-k3u1fbpfcp-zoom-1.image) ### 一、接口文档的幼年体:word ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d768fd899ca245b5923b322a3072a9a3~tplv-k3u1fbpfcp-zoom-1.image) 一开始是前后端分离,后端得告知前端接口的各项信息,方便前端调用。 那需要提供的信息也就那些,就用 word 写吧,于是就有了这样的接口文档: ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b686d0b5d71c4de5b8e0f72b6d20bc7a~tplv-k3u1fbpfcp-zoom-1.image) 问题似乎解决了,但项目嘛,是不停修改和迭代的,这样会导致: 这份接口文档是随着项目进行频繁改动的。 每更新一次,就需要给项目成员分发一次新的接口文档 于是: A.每改动一次就要新建一份,复制给项目组里很多人,这样一个文档复制来复制去,项目组里这么多人,谁都不知道拿到的是不是全新版本 ; B.改一点就要生成一个新文档,于是文件夹里的接口文档可能就是这种形式: ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0149f34cb470487a89919c12107f35c0~tplv-k3u1fbpfcp-zoom-1.image) 是谁哭了我不说。 这些痛点促成了接口文档的第一次进化: 从word版的接口文档进化成网页版的接口文档。 ### 二、接口文档的成长体:Markdown ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8a8f462a902c4c0fbf5debb2939550c5~tplv-k3u1fbpfcp-zoom-1.image) 网页版的接口文档多完美,只需要分发一个链接给项目成员保存起来。 这样,如果后端修改了接口,直接在网页里修改,就保证大家看到的都是最新版本的,也不用每次一有改动就发一份新文档给大家。 这样一个由markdown生成的静态的html 页面,一个接口的关键要素全都有 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/1e4fbf3c29274ec0906df711183226d9~tplv-k3u1fbpfcp-zoom-1.image) 问题解决! 但—— 新的问题又产生了。 这个接口文档是能用了,但又没那么好用,比如说: 1.写接口挺麻烦的,完全纯手工写,没有任何辅助工具,非常花时间 2.接口写完还不能立刻看到生成的接口文档的效果,写错了还要重新回去调 3.没有接口规范约束,接口文档怎么写,哪些参数要写,哪些不写,呈现形式怎么样全凭开发人员本身的业务水准。 于是就开始了新的一轮的进化——有人开发了一个工具,专门就用来写接口文档。 ### 三、接口文档的完全体:swagger ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e2677db0f58a40088389736008516df5~tplv-k3u1fbpfcp-zoom-1.image) 怎么写? 在swagger editor里编写符合swagger 语法的接口文档,来生成接口文档,编写完的接口文档可以在swagger editor的右侧实时预览: ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4d875ae18fb647899c3fc14e76897e2c~tplv-k3u1fbpfcp-zoom-1.image) 于是,进化到这个完全体阶段的接口文档工具已经实现了如下功能: 1.网页版接口文档支持的在线查看功能,当然他也有,而且这个接口文档的样式是符合open api3.0规范的,如果写得不符合语法,swagger editor 还会报错来纠正你。 一个标准的接口所应具备的信息:接口方法、接口路径、请求和响应参数,都能按照固定的格式呈现出来。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ebcd9c5baf68433bbaa554f2e24da855~tplv-k3u1fbpfcp-zoom-1.image) 2.它还具备了初步、简单的调试功能,就是接口请求参数为空格,填写参数、发送请求,就能返回响应参数 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/bf275b1935994299934806b1f5d03d2a~tplv-k3u1fbpfcp-zoom-1.image) 好像已经够用了对不对? 但——等等,这些如果是开发自己一个人用还行,但如果要运用到项目里,那么多的接口文档,蛮难管理的,swagger editor 不提供项目层级的归档和管理,维护也麻烦。 而且,到目前为止,也没有逃脱接口文档要靠手写生成的命运,还要去学swagger 注解,这样一来,学习成本有了,工作效率也提高不上去。 生成的接口文档,前端需要使用接口信息来调试页面,测试会用它来验证接口。 但目前接口文档的功能,对前端和测试的工作支持得还不够呀~ 好像....还可以更完美??! 有痛点就会有解决方案,于是接口文档开始了新一轮的进化之路,进入究极进化形态的接口文档工具是—— ### 四、接口文档的究极进化形态:Apifox ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a30c4f65b5064403ac4f414671b68b35~tplv-k3u1fbpfcp-zoom-1.image) ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/43b3b369899e47a2b74029bcea7ef9b8~tplv-k3u1fbpfcp-zoom-1.image) 想要团队协作?安排。 想要不用写代码就能生成接口文档?可以。 想要直接在接口文档上调试接口?支持。 接口还没上生产环境、但想要模拟数据可以调试前端页面?支持。 想要直接用接口数据来做自动化测试?安排。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b0dce77c6e8b4a199e71d1e9f5003ca4~tplv-k3u1fbpfcp-zoom-1.image) 于是一个究极进化形态的接口文档工具就诞生了。 ##### 首先是在已经存在的接口文档功能上做优化: A.可视化的接口设计页面,不用写swagger 注解 ,填完参数保存就是一份接口文档。 只要你懂接口的知识就能上手写,四舍五入这学习成本就是零。 ![接口文档编辑状态](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/2add3e9eb0344d0bbbf99bb864c92666~tplv-k3u1fbpfcp-zoom-1.image) ![接口文档只读状态](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5bbe9b06341d430d86bbe9c545b483d2~tplv-k3u1fbpfcp-zoom-1.image) B.一键导出接口文档,支持只分享部分接口文档,设置过期时间,设置密码 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/aaef7a8866a64d2e951e622a00034b56~tplv-k3u1fbpfcp-zoom-1.image) C.接口文档实时更新 一旦接口文档发生变更,数据会实时同步到参与项目的所有成员 ##### 其次是给前端和测试疯狂加外挂: A.接口文档页面支持在线调试 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/87feeb6cb8ad4fd9894d0c52d97c1d97~tplv-k3u1fbpfcp-zoom-1.image) 分享出去的接口文档页面支持简单的基础调试功能,如果你如要更加强大的调试辅助,则可以使用Apifox客户端。 客户端的调试功能对提取变量、断言、连接数据库等功能都做了可视化封装,不用写脚本,如果 有复杂的调试需求,仍旧支持脚本调试功能 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d1629ba66a2642d8b9f20db7e4ca9dd7~tplv-k3u1fbpfcp-zoom-1.image) B.支持生成代码 支持的代码种类也蛮多的,包括前后端常用的各种语言和框架,总共有130多种,javascript和swift,java等等生成的前端代码复制就能用。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/efb7e42de26d4d4694e39335e1422fe3~tplv-k3u1fbpfcp-zoom-1.image) 不仅支持生成接口请求代码,也支持生成数据模型代码,整个项目的代码,可以按需生成,然后自己再去做调整,这样需要写的代码量就大大减少了。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/385c83b29e514b20a744a8fc70bc5c97~tplv-k3u1fbpfcp-zoom-1.image) F.提供mock环境 在接口未上线时也能模拟接口请求,构造出高度真实的业务数据供前端测试页面,后端、测试进行接口的调试和测试 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8fc8d6565dc14ca7842690214e099437~tplv-k3u1fbpfcp-zoom-1.image) 可以复制链接到浏览器查看生成的在线文档: https://www.apifox.cn/apidoc/shared-cbb5c14c-0faa-4b4d-9f6e-7027cd57c702/api-21636796 ##### 最后是将接口的一整条工作链整合到它这一个工具里: A.支持项目层次的协作 每个接口归属于不同的模块,分属到不同的目录之中。 后端、前端、测试可以使用同一套接口数据源,也就是说接口创建出来之后,后端在上面维护,前端使用他做接口mock,测试用它做接口自动化,数据变更实时同步到各端,不需要切换多个软件。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0eac41bddee4474d9c00e37634f64f70~tplv-k3u1fbpfcp-zoom-1.image) B.支持导入postman,swagger等多达20多种格式的接口数据,零成本实现项目迁移 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6d3099fb429b482e88cb210cb100dc7b~tplv-k3u1fbpfcp-zoom-1.image) C.支持导出swagger,html,word 格式的接口文档,也不绑架用户,你想迁移到其他系统也大大方方成全你。 ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c18c35f5f5124b29835f94af1566ea62~tplv-k3u1fbpfcp-zoom-1.image) 这样一套组合拳打下来,基本上你能想到的接口文档该有的功能它都有了。 官网地址:[www.apifox.cn](https://www.apifox.cn/?utm_source=liam) ## 总结 因此,总结下来,接口文档一直以来都在不断地进化,战斗力也越来越强,也给研发人员提供了越来越到位的帮助,让他们能够少写不必要的代码,少做重复的工作。 大家可以根据自己项目的实际情况,选用合适的工具。

有疑问加站长微信联系(非本文作者))

入群交流(和以上内容无关):加入Go大咖交流群,或添加微信:liuxiaoyan-s 备注:入群;或加QQ群:692541889

707 次点击  
加入收藏 微博
1 回复  |  直到 2022-07-22 09:01:07
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传