最新版本:原来这才是Api文档的完全体

　　最新版本:原来这才是Api文档的完全体

　　一、简介

　　在目前主流的前后端分离模式开发下，需要有一个好用的接口文档。

　　**PS：以下几点是实际开发场景中遇到并实现的痛点**。

　　在项目的开发过程中，接口文档的存在可以让前端和后端工程师保持统一的数据信息概念。例如：“项目需求的接口字段和参数字段。只要将请求返回的参数记录在文档中，前端和后端工程师就可以针对接口文档统一编写自己的逻辑在写代码的时候，统一命名后，各个代码中就不会出现需要的函数的前端请求接口命名与后端返回接口的命名信息不一致的情况，这样可以大大避免故障排查失败，快速定位问题。

　　一个好的界面文档肯定会更直观、更容易维护、更容易保存。这些基本属性。但是到了21世纪的今天，还是有界面文档还是用word文档或者excel等笔记本记录工具来记录的。这样，文档是可用的，但是在项目的不断迭代中，文档需要不断的维护和更新，投入了不必要的成本。在项目交接的场景中，也交付了大量的接口文档。但是，在基于人工维护编写文档时，自然会出现删除参数、复制错误等错误操作的错误，从而无法很好地保证文档的正确性。

　　2.apifox在线接口文档

　　如今，许多界面文档工具层出不穷，如swagger、yapi、Knife4j等。但它们或多或少都有一些缺点。比如我们后端同学最常用的swagger-ui，有以下痛点：

　　提交的参数为 JSON，无法格式化。如果参数错误，查找起来很麻烦。返回的结果不能折叠。阅读时间太长了。

　　swagger-ui 在界面数量增加的情况下非常难用，而且没有分类菜单。

　　在最近的技术社区中，发现了一个api接口工具Apifox。相当于一个集Postman + Swagger + Mock + JMeter于一体的工具。Apifox 的界面文档是我遇到过的最亲密的程序员之一。不仅解决了我遇到的开发痛点，接口文档也很强大。

　　2.1 如何生成在线接口文档 2.1.1 第一步

　　首先去Apifox官网根据你对应的系统下载对应的Apifox客户端。当然，直接使用网页版并不妨碍我们后续的步骤。

　　下载完成后，我们打开客户端或者网页登录。如果你是第一次使用，可以先注册一个账号再登录。第一次使用的同学会发现如下页面进入。

　　因为演示，我会直接使用当前的示例团队和里面的示例项目。点击示例项目进入Apifox，会看到演示中使用的宠物店的界面分组。

　　2.1.2 第二步

　　为了让学生更恰当地使用 Apifox 替代到自己的项目中。我决定更多地模拟我们的真实使用环境，我在我的服务器上部署了一个名为 jeetcg-Boot 的开源项目。本项目有自己的自定义接口文档，但是可以导出一些OpenApi和Markdown格式的文档，然后我可以使用导出的接口文档来演示如何慢慢连接到网上提供的Apifox文档。

　　现在的同学有没有类似swagger格式的文档也没关系，因为Apifox支持21种格式的导入方式，把你的数据转换成Apifox。但也有例外。比如我上面提到的当前项目没有文档，其实你也可以通过Apifox的新界面添加当前项目的请求参数等信息，让你的项目从现在开始。有自己的接口文档。所以这里我们主要关注生成在线文档的操作如何创建一个新的在线文档。，所以这里不再详细介绍新的界面。此处操作不是很好的同学可以点击这部分文档帮助进行参考。

　　然后我将我的jeetcg-boot项目的接口文件导出为一个OpenApi.json文件，通过Apifox的导入功能将我当前项目的接口转入Apifox

　　

　　6

　　通过这么简单的步骤，我的项目界面就成功移植到了Apifox进行管理。

　　在这里我要表扬一下 Apifox 真的很漂亮的设计和舒适的排版，对于像我这样的颜值控。

　　2.1.3 第三步

　　这一步是我们目的的最后一步。确保我们的接口已经存在于项目中后，我们可以通过左侧的在线分享点击我们的新分享。

　　7

　　此时我们可以看到创建在线文档的信息表，需要填写接手当前项目的团队或其他小公司对于合作伙伴使用的这种场景，建议填写对应的匹配名称。密码访问可以为我们生成的在线文档提供一层加密保护，让不小心泄露的界面地址不会被其他人访问看到我们的界面设计等信息，所以这里要填写的小伙伴可以按照真实情况填写。过期时间可以决定我们当前生成的在线接口文档的过期时间。共享范围允许我们挑选和选择我们需要生成到在线接口文档的接口。我们可能会遇到这样一种场景，我们需要向开发团队提供一些功能复杂的接口，但又不想将所有接口都暴露给对方。这时候我们就可以选择需要提供的接口了。运行时环境是决定生成的在线接口文档调用什么环境的接口。这里的环境设置，同学们可以看看这部分。这里我们选择用来模拟我们的接口调用的环境。更多设置允许我们在我们的在线文档中显示这三个信息。我们可能会遇到这样一种场景，我们需要向开发团队提供一些功能复杂的接口，但又不想将所有接口都暴露给对方。这时候我们就可以选择需要提供的接口了。运行时环境是决定生成的在线接口文档调用什么环境的接口。这里的环境设置，同学们可以看看这部分。这里我们选择用来模拟我们的接口调用的环境。更多设置允许我们在我们的在线文档中显示这三个信息。我们可能会遇到这样一种场景，我们需要向开发团队提供一些功能复杂的接口，但又不想将所有接口都暴露给对方。这时候我们就可以选择需要提供的接口了。运行时环境是决定生成的在线接口文档调用什么环境的接口。这里的环境设置，同学们可以看看这部分。这里我们选择用来模拟我们的接口调用的环境。更多设置允许我们在我们的在线文档中显示这三个信息。运行时环境是决定生成的在线接口文档调用什么环境的接口。这里的环境设置，同学们可以看看这部分。这里我们选择用来模拟我们的接口调用的环境。更多设置允许我们在我们的在线文档中显示这三个信息。运行时环境是决定生成的在线接口文档调用什么环境的接口。这里的环境设置，同学们可以看看这部分。这里我们选择用来模拟我们的接口调用的环境。更多设置允许我们在我们的在线文档中显示这三个信息。

　　8

　　填写完所有信息后，我们可以点击保存，为我们的项目生成一个在线界面文档url。此时，我们复制当前生成的在线接口文档链接，打开即可找到我们的项目接口文档。

　　9

　　102.2 Apifox 的在线界面文档中的“魔力”是什么 2.2.1 文档中直接运行界面

　　细心的同学一定发现，选择一个界面后，在我们文档的右侧有一个运行按钮。单击该按钮将显示执行操作界面。点击发送后，我们可以看到返回的结果和我们的界面一模一样。返回响应的格式相同。调用正是我们在生成这个接口时选择使用的云mock环境，所以现在显示的数据是mock为我们生成的假数据。

　　但是，这对于获取文档的开发来说并不是太简单。可以直接在文档上测试当前接口是否满足要求，测试当前环境的接口状态是否正常。

　　在mock环境中调用的接口也方便前端程序员先开发后端，不会被后端同学卡住。

　　11

　　122.2.2 13种语言生成请求示例代码

　　在文档的中间，我们可以看到一些编程语言的非常明显的图标。它们是干什么用的？？

　　13

　　作为一个前端程序员，我自然会用javascript来介绍给我的同学。点击 javascript 图标，我们发现下面有一行选项卡提供选择。相信文章之前也是前端程序员的同学们并不陌生。这些是js常用的请求方法，在每个方法的选项卡下选择编辑器。会有代码使用这个方法来调用当前接口。**当我第一次看到这个功能时，我惊呆了。有这么亲密的互动吗？? **

　　

　　由于程序员的职业病，我们当然要测试生成的代码，他能跑吗？正确的。这里推荐你使用一些在线 IDE 来运行一些代码的方法。例如，流行的 stackblitz

　　我们把axios的代码复制到ide编辑器中，在线安装axios的库就可以在线运行了。

　　结果很明显，右边的打印和我们刚才跑的返回一模一样。这真的是牛肉。所以意味着这13种语言都可以生成自己的请求代码，在实际代码中验证当前接口请求的性能。

　　如果你想在这里测试更多的编程语言，那我就分享一个在线的ide小闪电，可以运行30多种语言。

　　2.2.3 生成模型代码

　　这个函数也是我很喜欢的一个函数，生成模型代码。主要是为返回的响应参数生成的模型代码。

　　比如我选择使用Typescript代码，那么它会自动生成一个带返回参数的typescript类型接口，这对于使用ts开发的前端同学来说是一个福音。不再需要一一复制请求返回的类型。现在可以直接复制粘贴到界面文档中，放入代码中。

　　当前代码生成模型的操作栏针对每种编程语言都有相应的配置开关。例如，对于 typescript，您可以打开仅生成类型定义，这将删除下面的转换代码。仅保留类型定义。并且还可以对运行时的json.parse的结果进行校验，确保我们返回的结果参数符合条件。

　　所以需要生成什么类型​​的模型代码就看同学们配置的需要了。

　　3. Apifox 在线分享接口文档的详细信息。这里我要说的是，我认为目前的这个接口文档确实是为了程序员的效率和易用性。

　　3.1.1 接口连接可直接点击复制：

　　3.1.2 文档整体布局

　　文档的整体布局是左右结构的，所以当我们的程序员在阅读文档的时候需要做一个试运行的时候，我们可以通过左右检查参数来检查是否有不符合要求的参数，这与顶部的swagger参数和底部的请求不同。需要上下移动，方便性大打折扣。

　　3.1.3 运行时批量编辑参数

　　在操作界面中，我们有时会有大量的请求参数，可能需要临时更改才能上厕所。表单中是否逐个更改是一件很痛苦的事情，而Apifox为开发者提供了批量编辑交互。更容易实现他们的目标

　　四、结尾

　　使用过 Apifox 后，相信你会或多或少对这款软件的细节和强大的功能印象深刻。因为一个软件工具的使命必须是为用户提供方便，处处简化用户的操作，让工作更有效率，这就是一个好工具的表现。

　　Apifox 确实有一点要说，它是一个有利于程序员的良心工具。

　　终极:吐血整理！顶级程序员的百宝箱来咯！| 原力计划

　　每个人都知道我是一个电子商务企业。在线界面多的在线问题如何排查？捕获数据包并查看数据。

　　JMeter

　　Apache JMeter 是 Apache 组织开发的基于 Java 的压力测试工具

　　是的，它用于压力测试。如何模拟大量请求？就用它吧。

　　短跑

　　Dash for mac 是一款配合 Mac OS 平台使用的软件编程文档管理工具，可以浏览 API 文档，管理代码片段。Dash 自带丰富的 API 文档，涵盖各种主流编程语言和框架。

　　开发文档

　　上面的兄弟，不过这个不用下载，是在线的

　　数据夹

　　DataGrip 是 JetBrains 推出的数据库管理产品。对于 JetBrains，开发者必须熟悉它。IDEA和ReSharper都是这家公司的产品，用户体验非常好。

　　一开始，我只是用它来看看我的同事正在使用一个很酷的界面。后来发现功能也很好吃，突出文字等等。你可以挖掘很*敏*感*词*。

　　视觉虚拟机

　　VisualVM 是 Netbeans 的一个配置文件子项目。JDK6.0 update 7已经收录，可以监控线程，内存情况，查看内存中方法和对象的CPU时间，已经被GC的对象，反向查看分配的栈（比如分配了哪些对象）到 100 个字符串对象）。

　　VisualVM 可以根据需要安装不同的插件。每个插件都有不同的关注点。有的主要监控GC，有的主要监控内存，还有的监控线程。

　　Iterm2

　　这是我用于日志故障排除的客户端工具。它还支持许多配置。可以直接ssh到跳板查看在线机器的状态等，还是需要在线排查的。

　　网*有道词典

　　有朋友想问帅青是什么情况，是不是有鬼畜混进来？

　　不，我们在开发它们时不知道很多单词，或者在命名它们时不知道单词的英文。仍然有必要检查它们。标准化的命名是你成为顶级大牛的第一步。你的名字全是A.B,C 当你的代码审核时，你的Leader会打电话给hr让你回家过年，然后再提交。新年来临之际，不要轻易尝试。

　　崇高的文本

　　这是一个文本记录的工具，也可以用来写代码，但是如果我们有IDE的话，它可以作为日常琐事记录的工具，临时文档处理的工具也是可以的，而且反正还是很有用的。

　　最近刚好有人才群里的人才打电话给我安利，给我做笔记和写博客的工具，说我的排版很好看。（我在飘）

　　安排！

　　

　　印象笔记

　　这可以说是陪伴我大学到现在的一个工具。数了几千个文件，记录了生活中的小事，学了编程之后的很多东西。我在收录里面。

　　我不会和其他笔记比较，因为我一开始使用的那个从来没有被替换过。

　　泰波拉

　　Typora 是我一直在为其编写 Markdown 的工具。它易于使用，但也可以切换模式。你相信吗？打字机模式、对焦模式、音源模式总有一款适合你。

　　ipic

　　我使用 Typora 的图片床。Markdown复制图片是不是从本地地址进来的，发到外网就失效了。但是，这个基于 Typora 的工具，你复制进去的时候可以直接上传到互联网上。现在，你可以在任何你想要的平台上发布。

　　Md2All

　　每个人都很好奇我的降价如何看起来如此美丽。其实我写完markdown后，转成html，就用了上面的工具。

　　写完就在这里打出来然后发出去。打字花了很长时间，忍不住夸了帅C。

　　图像处理 Adob​​e Photoshop CC 2019

　　ps，众所周知，正常的图片*敏*感*词*朋友（又开始YY了）

　　Adobe Premiere Pro CC 2019

　　这可能是最常用的视频处理软件了，非常好用！！！

　　功能太丰富了，喘不过气来。缺点是学习成本有点高，入门很快。成为大神需要很多时间。

　　Adobe After Effects CC 2019

　　不知道你看了多少视频。视频的很多特效都是由此制作的。下面还有一个我的演示。

　　GIPHY 捕获

　　有时候人们文章不想用静态图片来表达，而是想录制Gif*敏*感*词*来写代码，那么这个软件真的好用。

　　视频播放 KMPlayer

　　其实帅C，我心里有一个玩家神器，快点播吧。

　　可惜没过多久，直播就过早地死掉了。我将使用以下播放软件播放自己的视频。

　　因为很多电脑自带的格式可能不支持，而且我喜欢剪辑视频，一直在用。

　　

　　斗图

　　你有没有注意到我之前的很多 文章 表情实际上是在网上制作的？

　　碳

　　帅兵之前的文章里很多代码的图片都是这个网站生成的。有很多款式可供选择，非常漂亮。

　　代码LF

　　这个 网站 很有趣。如果你在写代码的时候不知道如何命名这些单词，可以去这里查看一下。他是GitHub的爬虫工具。看到大神之名，总会有想法。

　　注：我简单介绍一下上面的软件是做什么的，因为实在太多了，真正的功能还需要深挖。

　　总结

　　其实更香的工具太多了，这里就不一一介绍了，其实有一个很简单的方法，就是问，学，学。

　　我就是这样。看到Leader用什么工具，我问他是什么，好用吗？如何使用？

　　包括我写博客，其实才写了20多天。第一天准备写的时候，直接问三外（Java3y），你用什么开发工具，怎么用，包括他主要发布哪些平台，发布时间段，我会直接问。

　　他坐在我对面，因为我的猥亵而被迫说出真相，主要是因为最近有需要我为他写代码哈哈。

　　别人有这么多经验，会不会是软件不好？而且在使用过程中如果不知道，可以问问对方，是不是很香。

　　潺潺

　　我们先来看看人才交流群里一位人才提出的问题：

　　不知道大家还记得我之前写的幂等情况吗？

　　这就是下图中的情况。当我下单增加或减少 GMV 时，我会先去看看有没有流水。有的话就证明已经加了，我直接回。如果没有，请继续以下过程。

　　其实他提的问题很好，因为我们日常的开发是主从同步，读写分离，也就是说我们可能会加GMV，但是我们操作主库，他需要同步数据到奴隶图书馆，但是这个他在这个过程中被耽搁了。

　　这时候如果另一个系统重试订单号消息，你又进来了吗？你查看流水，发现没有流水，却以为自己没有加钱，进行了加钱的操作，结果耽误了。, 是不是加了两次。

　　正常开发中确实有，但是主从延迟应该是DBA（Database Administrator）考虑的，但是我说不能写有逻辑漏洞的代码，其实很简单，把他放到Redis中，设置一个时间约30分钟，可避免在此期间重复食用。如果延迟超过30分钟，问题已经很大了，DBA会知道的。

　　本文由吐血整理，大家吃好，记得给个赞哦！

　　原来的：

　　【结尾】

　　来吧，原力计划的升级版来了！2019年末，我们为您准备了一场交通盛宴！即日起，只要参与原力计划，文章达到要求，即可获得流量+*敏*感*词*的支持！

　　参与方式：发布原创文章时，在提交页面勾选原力计划即可参与。扫码戳详情↓