每个开发都不想写文档。当你不想写接口文档时,可以通过安装插件在 IDEA 里实现自动同步,一边写代码一边同步接口文档给你的前端、测试同学。以下内容手把手教你怎么操作(这里仅面向使用 IDEA 编辑器、遵循 Java Spring 框架注释规范的同学):
IDEA 插件市场里搜索 「 Apifox Helper 」,这是 Apifox 团队做的插件,可以非常方便自动生成接口文档并且同步到你的项目中。这个插件可以实现代码零入侵自动生产接口文档。
安装完成后,你可以选择同步到 Apifox 项目中,也可以直接导出 markdown 文档。如果是同步到 Apifox 项目,你还需要下载或注册 Apifox 软件,创建一个对应的项目:
(这里强烈推荐同步到 Apifox 项目,原因后面说)
插件安装成功后,要将 IDEA 内的项目与 Apifox 的项目进行相关联,需要配置令牌。在 IDEA 中进入插件设置界面 Preferences(Settings) > Apifox Helper 中填写即可。需要填写的基础信息有三个:
模块项目 ID 配置: 这项主要是进行代码模块名和项目 ID 的映射关系配置,在 Apifox 中对应项目的 [项目设置] 中选择 [基本设置] ,复制并保存项目 ID ,填写在以上的对应模块名处。
到这里,就完成全部的设置动作,可以实现文档的自动生成和更新同步了。说明一下:每个项目只需要开始的时候设置这一次,后面就不需要做这个操作了。
打开需要上传的 Controller 文件,右键选择「 Upload to Apifox 」。
去 Apifox 项目内,就可以看到刚才自动同步过来的文档了。
Apifox Helper 支持在 IDEA 中一键发起接口自测,不需要切换其他软件。在 IDEA 中选中需要调试的 API 文件,右键选择「 Call API 」发起请求就可以。
当然,以上只是简单版本的自动同步文档,没有什么特殊情况也就可以满足使用了。当然,可能会存在一些特殊的要求,比如说,设置接口 API 所在的文件夹名称、想要忽略某些 API 不同步等等情况。在他们的官方文档上是推荐使用配置文件的方式实现你各种特殊规则和要求的。详情可以自行去 Apifox 官方查阅。
很多开发都习惯用 Swagger ,用 Swagger 可以一定程度上解决自动生成文档的问题,但有一个很大的缺点:你需要写大量的注解,会对你的逻辑代码有入侵。并且在功能的全面性上不如 Apifox 。
Swagger:需要写注解,对逻辑代码有入侵,功能单一;
Apifox:使用标准的 Javadoc 注释,基本可以实现代码零入侵。同时它也支持同步 Swagger 的文档到项目里。还有 API Mock 、自动化测试等延伸功能。
推荐用法是可以省略 Swagger 这一步,直接安装这个插件使用就可以。
这个插件虽然支持导出 markdown ,但给别人分享分档的时候不是很方便,有更新的时候也不会同步,需要反复导出。使用 Apifox 项目就可以直接给别人分享一个链接就可以,你之后接口的更新也会直接同步,对方看到的永远是最新的。
另外,Apifox 这个产品本身还有很丰富的 API 调试、Mock 、自动化测试等功能,你的前端和测试也可以直接在上面做后续的工作。
当你通过插件同步了文档到 Apifox 项目里后,前端同学直接在文档内就可以一键点击「运行」调试,不需要再复制粘贴、也不需要和后端开发反复核对参数等信息。
Apifox 内置强大的 Mock 能力,可以直接生成非常智能、人性化的 Mock 数据。把接口文档中的 Mock 功能打开,复制链接到浏览器中回车一下,就能得到 Mock 数据。前端在后端的接口出来之前就可以通过 Mock 功能来制造假数据接口来进行开发和调试。
支持对文档界面的导航和样式做设计,比如导航做成符合产品的下拉菜单、注册登录按钮等,和产品网站融合度更高。
测试同学也可以在 Apifox 对接口进行测试。每个接口文档可以快速生成多个不同状态(成功、失败)的测试用例。
对测试步骤进行编排,模拟业务情景设置测试流程控制条件(循环、判断、等待):
Apifox 的产品体验比较好,适合团队各个角色一起在里面协作,也不需要再使用 postman 、swagger 多个工具切来切去了。有兴趣的同学可以前往 Apifox 官网体验、看使用文档。
官网地址:www.apifox.cn
这是一个专为移动设备优化的页面(即为了让你能够在 Google 搜索结果里秒开这个页面),如果你希望参与 V2EX 社区的讨论,你可以继续到 V2EX 上打开本讨论主题的完整版本。
V2EX 是创意工作者们的社区,是一个分享自己正在做的有趣事物、交流想法,可以遇见新朋友甚至新机会的地方。
V2EX is a community of developers, designers and creative people.