代替swagger的api接口神器

Posted 2023-03-02 墨家巨子@俏如来

自动化API文档-APIFOX

文章作者：老杨

一：概述

大家在后端开发开发过程中，最痛恨的两天事情：1.写文档，2.别人不写文档。而我们后端开发，必定经历的事情就是要和前端&测试对接，我们需要把我们的业务接口告知他们，让前端和测试能：1.并行开发，2.对接联调实现完整功能，3.测试根据接口完成测试用例编写和测试，所以避免不了的就需要我们出接口文档。我们出文档又回归到了三种方式：1.手工编写（任务给谁，谁骂），2.swagger，3.侵入式注解。

1. 手工编写，如果是开发前定好接口，避免不了的设计不到位，后期重复修改，还有会占用前期大量时间，小团队耗不起。
2. Swagger和侵入式注解，都需要在我们的代码中额外增加各种注解，对我们的代码可读性来说，点都不友好。

swagger嵌入式生成文档案例：

来吧，吐槽把。为什么我还要把逻辑代码和文档注解写在一个地方？这跟在 html 里写样式代码有什么区别？

来吧，上正题，今天给各位IT精英推荐ApiFox，JavaDoc和Idea插件一体化。解决你的烦恼问题，初步预计，这会成为业务未来主流，大家值得使用。

二：实操

1. Apifox idea 插件--Apifox Helper

注：如果下载不下来，重试几次

这个插件用起来挺简单的，关键在于，它把从代码到 API 文档的这一步，用最方便的办法解决了。API 相关的定义再也不需要用侵入式的方式写到代码注解里，而是清清爽爽地写成像这样的注释就可以了。

注释里面的 @param, @link, @return 这些就是标准的 Javadoc 注释，在 JDK 里定义好的，全球通用。

只要写好了 Javadoc，自动生成 API 文档就只需要三步。

第一步，从 IDEA 插件市场下载 Apifox Helper，配置好你的 Apifox 令牌。

注：令牌到官网去微信关注登录，然后在

第二步，在 IDEA 里点右键，【Upload to Apifox】,就能一键从你的代码生成 API 文档。

Upload to Apifox可以生成单个接口，也能一键把 Controller 里面的所有接口全部生成！甚至把整个项目上右键一起生成接口文档。

第三步，在 Apifox 里面分享文档。我就拥有了一个方便的，美观的，可以团队协作的，还能在线调试的，完美的 API 文档。

到此，你就可以像使用Postman一样在这里完成接口的查阅，测试。nice！

三：经验总结

1. 写完一个接口，首先自测，不着急上传到文档。可以在代码里点右键【Call API】，就可以直接在 IDEA 里发起接口请求，特别爽！根本不需要用 Postman！

 

1. 自测没问题了就可以点右键【Upload to Apifox】，如果是新写的接口，就会在 Apifox 里新增一个 API；如果是原本的接口有修改，就会自动更新已有的 API。
2. 把前端和测试的同事都直接加进 Apifox 的项目团队里。这样，只要我这边上传了 API，他们在 Apifox 里面直接就能看得见，根本不需要我发一个 API 文档给他们。API 文档不但自动生成了，开发人员我根本不需要管它！
3. 前端和测试可以直接用 Apifox 来调接口和做测试。如果接口有调整，我就直接在代码里改，然后重新 Upload 一下，前端和测试那边看到的接口就是最新的了。
4. 如果 API 需要开放给外部的合作团队，这个时候就需要专门输出一个 API 文档了。我在 Apifox 的“在线分享”选择开放给他们的接口，配上环境，就是一个完美的 API 文档了，还能在线直接运行和生成代码。

三方公司打开链接即可查看：

文章结束，如果喜欢的话请给个好评，你的鼓励是我最大的动力谢谢。