IDEA 版 API 接口神器来了,一键生成文档,贼香!

简介: IDEA 版 API 接口神器来了,一键生成文档,贼香!

前言

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


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


IDEA 插件市场里搜索 Apifox Helper ,这是 Apifox 团队做的插件,可以非常方便自动生成接口文档并且同步到你的项目中。这个插件可以实现代码零入侵自动生产接口文档。


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


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


注册/下载地址: http://apifox.cn/b3guide1 ,直接微信扫一扫就可以,非常简单。


创建项目:点击创建团队 >新建项目,填入对应的项目名称。(这里强烈推荐同步到 Apifox 项目,原因后面说)

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


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


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

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


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



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

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

1、打开需要上传的 Controller 文件,右键选择「 Upload to Apifox」。


2、去 Apifox 项目内,就可以看到刚才自动同步过来的文档了。

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

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

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


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

和 Swagger 有啥不一样?

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


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


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


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

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

这个插件虽然支持导出 Markdown,但给别人分享分档的时候不是很方便,有更新的时候也不会同步,需要反复导出。使用 Apifox 项目就可以直接给别人分享一个链接就可以,你之后接口的更新也会直接同步,对方看到的永远是最新的。



另外,Apifox 这个产品本身还有很丰富的 API 调试、Mock 、自动化测试等功能,你的前端和测试也可以直接在上面做后续的工作。

调试方便

当你通过插件同步了文档到 Apifox 项目里后,前端同学直接在文档内就可以一键点击「运行」调试,不需要再复制粘贴、也不需要和后端开发反复核对参数等信息。


云端 Mock

Apifox 内置强大的 Mock 能力,可以直接生成非常智能、人性化的 Mock 数据。把接口文档中的 Mock 功能打开,复制链接到浏览器中回车一下,就能得到 Mock 数据。前端在后端的接口出来之前就可以通过 Mock 功能来制造假数据接口来进行开发和调试。



文档页面的布局设计能力

支持对文档界面的导航和样式做设计,比如导航做成符合产品的下拉菜单、注册登录按钮等,和产品网站融合度更高。

自动化测试能力

测试同学也可以在 Apifox 对接口进行测试。每个接口文档可以快速生成多个不同状态(成功、失败)的测试用例。


对测试步骤进行编排,模拟业务情景设置测试流程控制条件(循环、判断、等待):

Apifox 的产品体验比较好,适合团队各个角色一起在里面协作,也不需要再使用 postman、swagger 多个工具切来切去了。有兴趣的同学可以前往 Apifox 官网体验、看使用文档。

相关文章
|
5天前
|
安全 数据挖掘 API
【实时数据】商品详情API接口系列开发
商品详情API接口系列对于电商平台至关重要,它们为开发者提供了实时、准确的商品信息,使得在线销售和展示商品变得更加高效和精准。以下是几个主要的电商平台及其商品详情API接口的介绍:
|
14天前
|
监控 供应链 搜索推荐
数据驱动电商:深度利用淘宝API接口掌握商品详情
本文探讨了如何利用淘宝API接口获取商品详情数据以助力电商决策。通过API,商家能获取商品标题、价格、库存等信息,从而进行市场分析、库存优化、定价策略制定及个性化推荐。步骤包括注册获取API权限、理解文档、构建数据收集流程、处理分析数据以及应用结果。示例代码展示了如何用Python调用API获取商品详情。善用API和数据驱动策略可在电商市场中取得优势。请注意遵循淘宝的API使用规范。
|
19小时前
|
存储 前端开发 安全
Nuxt3 实战 (十):使用 Supabase 实现 RESTful 风格 API 接口
这篇文章介绍了如何使用Supabase实现RESTful风格的API接口,用于网站分类和子站点的增删改查(CURD)功能。文章首先阐述了表设计,包括ds_categorys和ds_websites两张表的列名、类型和用途,并提到了为每张表添加的user_id和email字段以支持用户身份识别。接着,文章描述了接口设计,以ds_websites表为例,说明了如何通过RESTful API实现CURD功能,并给出了使用SupabaseClient实现插入数据的相关代码。文章最后提供了项目效果预览和总结,指出学习了Nuxt3创建接口及调用Supabase数据库操作。
Nuxt3 实战 (十):使用 Supabase 实现 RESTful 风格 API 接口
|
1天前
|
数据采集 机器学习/深度学习 搜索推荐
Python第一章(图片与API接口)
Python第一章(图片与API接口)
|
1天前
|
JSON API 数据格式
网易云音乐随机歌曲调用API接口
网易云音乐随机歌曲调用API接口
7 1
|
6天前
|
人工智能 自然语言处理 API
云栖发布:通义听悟AI能力再进化,开放API接口
云栖发布:通义听悟AI能力再进化,开放API接口
|
6天前
|
JSON 安全 API
电商开发者必读:微店商品详情API接口全解析
微店商品详情API让开发者能通过商品ID获取包括名称、价格、库存、描述和图片在内的详细信息。开发者需注册账号、获取API密钥和访问权限,并熟悉HTTP请求。请求示例为GET方法,响应数据以JSON格式返回。注意错误处理、保密性、频率限制和数据验证,以确保安全和高效使用。
|
6天前
|
搜索推荐 Java API
探索淘宝API接口:为电商业务开启无限可能
淘宝API接口是淘宝平台为第三方开发者提供的一组开放接口,通过这些接口,开发者可以获取淘宝平台上的商品信息、交易数据、用户行为等关键数据,并基于这些数据开发各种应用。淘宝API接口支持多种编程语言,如Java、Python、PHP等,方便开发者根据自己的需求进行选择和开发。
|
7天前
|
数据可视化 Java API
【JAVA】javadoc,如何生成标准的JAVA API文档
【JAVA】javadoc,如何生成标准的JAVA API文档
7 0
|
9天前
|
SQL 缓存 测试技术
RESTful API设计的最佳实践:构建高效、可维护的Web服务接口
【6月更文挑战第11天】构建高效、可维护的RESTful API涉及多个最佳实践:遵循客户端-服务器架构、无状态性等REST原则;设计时考虑URL结构(动词+宾语,使用标准HTTP方法)、使用HTTP状态码、统一响应格式及错误处理;确保数据安全(HTTPS、认证授权、输入验证);实施版本控制;并提供详细文档和测试用例。这些实践能提升Web服务接口的性能和质量。