横空出世!IDEA 版 API 接口神器来了,一键生成文档!

liam
• 阅读 641

每个开发都不想写文档。当你不想写接口文档时,可以通过安装插件在 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 版 API 接口神器来了,一键生成文档!

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

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

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

横空出世!IDEA 版 API 接口神器来了,一键生成文档!

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

横空出世!IDEA 版 API 接口神器来了,一键生成文档!

  1. 模块项目 ID 配置: 这项主要是进行代码模块名和项目 ID 的映射关系配置,在 Apifox 中对应项目的【项目设置】中选择【基本设置】,复制并保存项目 ID,填写在以上的对应模块名处。
    1. 横空出世!IDEA 版 API 接口神器来了,一键生成文档!

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

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

  1. 打开需要上传的 Controller 文件,右键选择「 Upload to Apifox」。
    1. 横空出世!IDEA 版 API 接口神器来了,一键生成文档!
  2. 去 Apifox 项目内,就可以看到刚才自动同步过来的文档了。

横空出世!IDEA 版 API 接口神器来了,一键生成文档!

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

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

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

横空出世!IDEA 版 API 接口神器来了,一键生成文档!

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

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

横空出世!IDEA 版 API 接口神器来了,一键生成文档!

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

和 Swagger 有啥不一样?

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

Swagger:需要写注释,对逻辑代码有入侵,功能单一;

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

推荐用法是可以省略 Swagger 这一步,直接安装这个插件使用就可以。

下载链接:www.apifox.cn

点赞
收藏
评论区
推荐文章
kenx kenx
3年前
SpringBoot 优雅整合Swagger Api 自动生成文档
前言一个好的可持续交付的项目,项目说明,和接口文档是必不可少的,swaggerapi就可以帮我们很容易自动生成api文档,不需要单独额外的去写,无侵入式,方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目,剩余的时间就可以去约妹子啦整合swaggerapi这里我们自己去整合swaggerapi比较麻烦,要导入好几个包
Symbol卢 Symbol卢
2年前
聊聊前后端接口对接的那些事
前言在现在的前后端分离的项目开发中,为了不影响项目的进度,都是前后端同时进行开发。为了不影响咱们前端开发的进度,通常都是由后端同学,先提供接口文档,然后前端同学对照这接口文档来进行数据的模拟来完成前后端对接的工作。这里的数据模拟其实也就是大家平时所说的mock数据,那么前端当中有哪些方式来实现mock数据呢???…(⊙_⊙;)…咱们接着往下聊!(●^o^●)
liam liam
2年前
程序员的摸鱼加速器!
最近趁摸鱼时间体验了一款神器,堪称后端前端们的摸鱼加速器,测试们的寿命催化剂。那就是:Apifox。中国自主研发的集文档、接口调试、Mock、接口自动化测试一体的协作平台。一套系统、一份数据,可解决多个系统之间的数据同步问题。定义好接口文档,则接口调试、数据Mock、接口测试就可以直接使用,无需再次定义;接口文档和接口开发调试也可以同一个工具,接口调试完成后
Stella981 Stella981
3年前
Hi,给他介绍一款markdown的帮助文档生成器
     当今大多数的团队都实现了前、后端分支。前端与后端的沟通都是通过接口来实现的(一般情况下都是webapi接口)。这种情况你肯定需要一个接口查询的帮助文档,这个当然用swagger都可以实现。但做为前端开发的我们是否也应该考虑把自己写的组件以帮助文档的方式公开都团队其他人员使用。就像iview,easyui等UI组件都有自己的帮助文档。今天我们都介绍
API 小达人 API 小达人
1年前
「实用技巧」后端如何使用 Eolink Apikit 快速调试接口?
程序员最讨厌的两件事:1.写文档;别人不写文档。写文档、维护文档比较麻烦,而且费时,还会经常出现API更新了,但文档还是旧的,各种同步不一致的情况,从而耽搁彼此的时间,大多数开发人员不愿意写API文档。EolinkApikit为后端工程师提供API文档的创建与自动化生成、快速接口调试、以及API文档版本管理功能,协助后端工程师快速编写文档,调试接口,以及支持版本控制恢复历史记录。通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好接口文档,接口调试、数据Mock、接口测试就可以直接使用,无需再次定义。接口文档和接口开发调试使用同一个工具,接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确!
API 小达人 API 小达人
10个月前
Eolink Apikit 快速发起 API 测试,一键生成测试数据
我们在测试接口时,通常需要先创建API文档,再根据API文档生成测试用例。未创建该接口文档,仅临时调试接口,EolinkApikit支持创建API快速测试页面,输入接口相关的信息即可进行快速测试。EolinkApikit支持操作数据库,API测试时,可以一键生成测试请求数据。这可以减少数据输入步骤,提高调试接口效率。
API 小达人 API 小达人
9个月前
国投证券如何引领金融行业的 API 治理创新?
在开发、对接阶段,因为API资产统一托管在平台上,因此可以通过API文档快速生成MockAPI,前端开发人员只需要通过MockAPI就可以快速对接后端接口,将前后端开发工作解耦,提高工作效率。在测试阶段,测试人员可以基于API文档快速创建单元测试用例,API文档和测试用例之间自动形成绑定关系。当API发生变更的时候,平台可以将数据同步到测试用例,并且可以与CI/CD流程结合,实现单元测试用例的自动化回归测试工作,并且将测试报告推送给相应邮箱。
liam liam
1年前
超简单!Java 项目自动生成接口文档教程
你还在用word、markdown埋头苦干写?写文档这件事恐怕是每个开发都万分抗拒的事情了。本篇文章详细教你如何利用插件工具,在IDEA中自动生成API文档。先来看看从IDEA中生成文档的效果如下图。下图是使用Apifox插件(Apifoxhelper)从
API 小达人 API 小达人
1年前
【遥遥领先】Eolink IDEA 插件:零代码入侵,自动生成接口
对于开发同学来说,无论是新增还是修改接口文档,都需要在开发工具和接口管理工具上同步最新的数据。而且接口文档变更内容会比较琐碎和频繁。那么是否有更轻便的同步接口数据方式呢?我们提供了一个高效方案:在开发工具上基于接口代码片段,一键生成API文档,支持在开发工具中调试,并可一键上传至EolinkApikit的代码仓库中。这样不仅可以减少界面的操作和系统间的切换,还可以在开发工具上完成琐碎和频繁的接口文档更新,是当前CODETOAPI的最佳实践。
API 小达人 API 小达人
1年前
【前端小技巧】如何使用 Eolink Apilkit 调用 Mock
在开发过程中,进度比较赶的情况下,前端人员当页面写完时,后台的接口还没写完,等要交付的时候后端才把接口给你,这个时候就很尴尬。这个时候Mock就可以很好的解决这个问题,前端团队可以在API还没开发完成的情况下,借助MockAPI实现预对接,加速开发进程。测试团队可以通过MockAPI解决不必要的系统,完成集成测试。EolinkApikit为前端工程师提供API文档管理,快速接口测试,以及MockAPI创建与调用,及查看文档变更历史的能力。有助于前端工程师快速查看API文档详情与历史记录,快速生成和使用MockAPI提前进行页面效果验证。