bingkele (冰可乐)

IDEA 版 API 接口神器来了，一键生成文档！

bingkele — Tue, 21 Feb 2023 13:50:11 +0800

每个开发都不想写文档。当你不想写接口文档时，可以通过安装插件在 IDEA 里实现自动同步，一边写代码一边同步接口文档给你的前端、测试同学。以下内容手把手教你怎么操作（这里仅面向使用 IDEA 编辑器、遵循 Java Spring 框架注释规范的同学）：

首先，你需要安装一个插件

IDEA 插件市场里搜索「Apifox Helper」，这是国内一个做 API 协作管理平台的厂商（Apifox）做的插件，可以非常方便自动生成接口文档并且同步到你的项目中。这个插件可以实现代码零入侵自动生产接口文档。

IDEA 安装插件：打开 IDEA > Preferences(Settings) > Plugins，搜索 Apifox Helper，点击安装。这里如果存在安装速度慢，你也可以去 Jetbrains Marketplace 的官网下载。

安装完成后，你可以选择同步到 Apifox 项目中，也可以直接导出 markdown 文档。如果是同步到 Apifox 项目，你还需要下载或注册 Apifox 软件，创建一个对应的项目：

注册/下载地址：http://apifox.cn ，直接微信扫一扫就可以，非常简单。
创建项目：点击创建团队 >新建项目，填入对应的项目名称。

（这里强烈推荐同步到 Apifox 项目，原因后面说）

第二步，把你 IDEA 中的项目和 Apifox 的项目关联

插件安装成功后，要将 IDEA 内的项目与 Apifox 的项目进行相关联，需要配置令牌。在 IDEA 中进入插件设置界面 Preferences(Settings) > Apifox Helper 中填写即可。需要填写的基础信息有三个：

Apifox 服务器地址：默认 Apifox API 服务地址为 https://api.apifox.cn，默认就填好了，不需要修改。

填写 Apifox 个人访问令牌：在 Apifox 个人头像处的【账号设置】中选择【API 访问令牌】，新建令牌后复制生成的 Token 填写到以上插件设置中。

模块项目 ID 配置：这项主要是进行代码模块名和项目 ID 的映射关系配置，在 Apifox 中对应项目的【项目设置】中选择【基本设置】，复制并保存项目 ID，填写在以上的对应模块名处。 .

到这里，就完成全部的设置动作，可以实现文档的自动生成和更新同步了。说明一下：每个项目只需要开始的时候设置这一次，后面就不需要做这个操作了。

第三步，自动生成接口文档

打开需要上传的 Controller 文件，右键选择「Upload to Apifox」。 . 1.
去 Apifox 项目内，就可以看到刚才自动同步过来的文档了。

当后续接口代码有变动或更新时，再次点击「Upload to Apifox」就可以同步。

为什么推荐创建一个 Apifox 项目？

这个插件虽然支持导出 markdown，但给别人分享分档的时候不是很方便，有更新的时候也不会同步，需要反复导出。使用 Apifox 项目就可以直接给别人分享一个链接就可以，你之后接口的更新也会直接同步，对方看到的永远是最新的。另外，Apifox 这个产品本身还有很丰富的 API 调试、Mock、自动化测试等功能，你的前端和测试也可以直接在上面做后续的工作了。这里不细说，有兴趣的可以去找他们官方文档了解。

有了这个插件，你还可以直接在 IDEA 里调试

Apifox Helper 支持在 IDEA 中一键发起接口自测，不需要切换其他软件。在 IDEA 中选中需要调试的 API 文件，右键选择「Call API」发起请求就可以。

当然，以上只是简单版本的自动同步文档，没有什么特殊情况也就可以满足使用了。当然，可能会存在一些特殊的要求，比如说，设置接口 API 所在的文件夹名称、想要忽略某些 API 不同步等等情况。在他们的官方文档上是推荐使用配置文件的方式实现你各种特殊规则和要求的。详情可以自行去 Apifox 官方查阅。

和 Swagger 有啥不一样？

很多开发都习惯用 Swagger，用 Swagger 可以一定程度上解决自动生成文档的问题，但有一个很大的缺点：你需要写大量的注释，会对你的逻辑代码有入侵。并且在功能的全面性上不如 Apifox。

Swagger：需要写注释，对逻辑代码有入侵，功能单一；

Apifox：可以基本实现代码零入侵，使用标准的 Javadoc 注释就可以自动生成。同时它也支持同步 Swagger 的文档到项目里。还有 API Mock、自动化测试等延伸功能。

推荐用法是可以省略 Swagger 这一步，直接安装这个插件使用就可以。插件直接插件市场搜索：Apifox Helper

官网：www.apifox.cn

聊聊 API 管理 - 开源版到 SaaS 版

bingkele — Thu, 21 Jul 2022 16:36:05 +0800

API 管理这个话题近些年听到的频次越来越多，这本质上是个 web 领域的发展有关，也和开发协作方式有关--前后端分离代替了全栈工程师 hold all 的局面，强调的更多的是 API 复用、分工和协作细化。 API 管理的重要性不言而喻，每家公司随着业务的发展，多多少少都会涉及到；从开源社区的产品到国内各类商业化产品，可以看到大家对于 API 管理是越来越重视的。

为什么需要管理 API

Little story

结合自身的开发经历，我们先讨论下，为什么需要管理 API

1、在实习的时候是在一家小的游戏公司，人不多，一个产品；当时技术经理的安排是一个后端 + 一个前端的组合开发，大家都在一个办公室，接口 API 交付依赖的是“讲一声”；这种形式减少了接口定义、审核以及一些文档的编写，面向指定接口的一对一交付；其实这个过程很顺利，还可以培养同事之间的关系；直到有一天，我对接的前端同事离职了，来了一个新的伙伴，然后我们也刚好要产品升级；每当我改一个接口，前端同学或者测试同学就说，接口不行了。后来我也走了，换了新的后端，“口口相传”API 就断代了。

2、第二个 case 是做一个 web 项目 (应用元数据管理)，前后端分离的；我们是先定义有哪些接口，然后再定义参数、返回结果以及这个字段的含义；是面向文档交付的；每个接口开发完之后发布到测试环境，然后他去编写前端接口调用测试；这种耦合度非常高，前端的节奏受制于后端的节奏。

3、前面两种面向的都是一个端，再到后来，开始做基础平台，面向的有 web、app（安卓、IOS），各种三方，我们使用了开源社区的 Yapi 做了私有化部署，能够基本满足日常的需求（也比较痛苦，后面会提到）。

API 管理带来的好处

从前一节的 case 来看，API 管理的过程是在逐步完善的，从以工程师视角管理到更规范化的基于管理工具的管理；“口口相传”会随着工程师的更替而逐渐失去管控，直到无法追溯；基于文档的管理，从实际情况来看，两次变更之后就会慢慢的弱化文档的地位（改一次接口，就得改一次文档），取而代之的还是工程师主导；还有一点是，不管是基于“口头协定”还是文档，接口在没有交付之前是不具备可测试性的，而且面向的主体单一，一旦使用端的数量多了，资源分散和协调的人力成本将指数级增长。

API 管理不仅仅是提高技术能力，而是帮助推动业务更上一层楼，好的 API 管理可以带给我们的收益是非常大的。

【敏捷开发和快速业务支撑】：协助我们能够快速的创建、共享、监控和调整 API，不需要额外的协同沟通成本而导致生产力下降。
【工作流程自动化】：可以从 coding 到 CI 再到 API 管理工作实现自动化同步，绕过繁琐的 API 设计、审核、测试沟通等等；与现有的基础设施绑定起来，提高效率。
【维护数据完整性和安全性】：不会随着人员变动而导致 API 数据丢失，API 的变更可以通过管理平台的 log 逐一追溯。

我们现在是怎么做的，有哪些问题

关于 API 管理这块，我们现在还有专门的 API 技术工作组来负责统筹所有服务的 API 相关事项，包括设计规范、自动化工具套件建设、API 管理建设等等。但是由于多语言栈、历史接口文档零散、开源工具停止维护等原因，导致相关工作推进起来非常麻烦。

历史接口文档有的在 confluence，有的在飞书，有的在 yapi，维护不同工具之间数据一致性非常困难、低效。
随着使用的深入，开源产品功能上的一些 bug 会被放大（需要进行二次开发，修复版本问题、权限问题等等），而且开源产品的持续维护性没有保障，在统一工具上很难达成统一。
对于需要编排的接口，处理起来很麻烦，需要额外的指导文档，step by step，又会导致数据一致性问题产生（指导文档和接口在不同地方管理）

这些问题也迫使我们在不断寻求各种解决方案，也包括各种商业 API 管理工具的调研，以便于能够给我带来新的解题思路；国内目前企业级的主要 Apifox、ShowDoc、，国外有 boomi、apigee 等（国外的相较于国内的产品要贵不少）；下面主要从功能上对比当前使用 Yapi 和在调研 Apifox（公网 SaaS 版免费）。

Apifox & Yapi

下面主要是从功能上来看，从持续维护方面来说，Yapi 是社区驱动，没有多少利益牵扯，从 github 上看已经有很久没有新的提交了，issue 也缺乏跟进（情怀很重要，但是吃饭更重要，维护一个产品真的很难，是需要给 Yapi 开发小伙伴点赞的）；Apifox 是商业产品，在持续维护和技术支持上不用怎么担心。

快速部署

工具调研除了功能之外，最核心的是易上手性；从我们维护部署的 Yapi 来看，环境配置这块是有些复杂的，这一点网上也有相同的痛点

单部署和环境配置来说，Yapi 有很多文章介绍，说明官方文档本身对于不同环境的适配性有点欠缺，毕竟免费。
Api fox 入手极简，这个是有点出乎意料的，不管是客户端版本和 Web 端，创建账户之后即可使用（托管 SaaS，屏蔽了这些环境和配置上的差异）。

功能区分布

YAPI

Apifox

结论：总体来说 SaaS 版本的 Apifox 相比于 Yapi 来说，功能面板更加丰富些；包括了项目统计，在线分享，代码生成等。操作上来说，Yapi 需要从分类 -> 项目 -> 接口，个人感觉内部的功能 tab 没有 apifox 的合理。

接口详情

Yapi

Apifox

结论：接口信息整体差异不大，功能上多了云端 Mock 和快速请求，Apifox 直观感受更加丰富和聚焦。

Mock 能力

Yapi

Apifox

结论：区别不大，但是 Apifox 有独立的数据模型管理 (可复用的数据结构，定义接口返回数据结构及请求参数数据结构（仅 JSON 和 XML 模式）时可直接引用。支持模型直接嵌套引用，直接 JSON/XML 智能导入，支持 oneOf、allOf 等高级组合模式)，Yapi 没有。

数据导入导出

Yapi

Apifox

结论：apifox 在支持的导入源上更丰富，可以满足企业的不同诉求。（Yapi 好像不支持 Swagger 1）

Special

1、数据库操作

支持读取数据库数据，作为接口请求参数使用。支持读取数据库数据，用来校验 (断言) 接口请求是否成功。

这个其实挺有意思的，在很多情况下，我们的测试其实需要依赖具体的数据库才能模拟出更贴合实际场景的用例；测试用例上，大多都是基于 H2 这种内存数据库，而依赖 mock 和实际场景又会有一些差异；尤其对于多云环境部署的，不同的云提供的 DB 服务还有一些特殊（比如使用的数据库不同，有的是 Mysql，有的是 Oracle），代码层面的适配无法通过 mock 来体现，那 Apifox 这个就非常赞了。

2、自动化测试

提供接口集合测试，可以通过选择接口（或接口用例）快速创建测试集。这一点在前文的介绍中有说过，这个是我们当前的痛点之一，就是组合接口的自动化测试。

更骚的是还能给出完整的测试报告（支持导出），再也不用担心前端同学说“你不行了”。

3、生成在线接口文档

我们当前对外部合作的三方是不友好的，由于业务迭代速度和一些定制化的需求，开放平台能提供的接口 API 非常有限。大多数情况下，我们都是通过文档将接口的调用逻辑、参数及返回结果语义发送给外部用户（出于安全管控，外部没法直接访问我们的 API 平台，API 接口截图也会留痕）。
Apifox 项目可“在线分享”API 文档，分享出去的 API 文档可设置为公开或需要密码访问，非常方便与外部团队协作，完成协作之后也不用担心合作方会把接口扩散出去（变更密码或者关闭授权）。

可以感受下：https://www.apifox.cn/apidoc/s/ce387612-cfdb-478a-b604-b96d1dbc511b/http/5041285

1-3 所提供的能力确实是戳中了我们的痛点，这可能也是绝大多数公司所共有的问题，Apifox 这几点在产品上的设计个人觉得还是非常优秀的。

总结

本文主要结合自身的一些经历以及当前工作中所遇到的问题，对正在使用的开源产品 Yapi 和在调研的 Apifox 做了一些对比和介绍；整体来看 Apifox SaaS (免费版) 相较于 Yapi 来说，还是有不少优势的。

如果是个人开发者，小团队，或者研发预算有限的公司来说（没有任何功能限制，没有团队使用人数限制，也没有项目和接口数量限制），白嫖即可；对于常规保密级别的项目，SaaS 版本其实已经够用了。如果对于安全和保密要求较高，可以考虑私有化部署。关于 Apifox 更多可以见其官网 www.apifox.cn