文档章节

加速前后端并行开发,JApiDocs 可以帮到你

叶大侠
 叶大侠
发布于 2017/08/18 12:43
字数 1264
阅读 1.4W
收藏 59

精选30+云产品,助力企业轻松上云!>>>

我的博客原文

背景介绍

一般公司的开发流程应该是这样的,产品评估会议完了之后,接着就是各就位的设计,开发了,当然这个过程中会有一些反复的交叉。我们这里主要讨论在评估完成之后,原型交给开发的这个节点。在这个节点上,如果没有接口文档,UI 稿也还在设计,那前端开发人员只能无奈的陷入等待,然后后面时间紧迫,不得不加班完成。

develop flow

接口文档非常重要,但什么时候写?谁来写呢?我的建议是接口的设计应该是交给有一定经验的后端开发人员来提前设计好,然后分给后端人员去实现,同时也交付接口协议给前端,两端并行开发。但实际情况是由于文档本身就是一个工作量,后端人员也不太关心前端的工作进度,而且提前设计的接口后面也可能会有一些小改动,对自己来说得不偿失,所以就变成了后端同学懒得去提前设计,一直等接口开发完了再去完善文档,这可能算好的了,有些团队就直接把一个 URL 贴到聊天框里面了事,前端同学只能去翻聊天记录。

这里顺便提一下没有接口文档的后果,一个生命周期比较长的产品,肯定经历了多个版本的迭代,接口的数量也会变的庞大,新进来的开发已经没办法在短时间之内了解每个接口的作用了,当碰到相同功能的时候,很容易又写了个差不多的接口,重复的接口越来越多,当其中一个有问题时,你要处理的可不仅仅是一个地方;更惨的是客户端人员,这个接口对他来说就是个黑盒子,要打开这个盒子,只能不断找服务端的问问问了,极大的沟通成本啊~

在前后端协作中还有一个问题就是,即使有了完善的 API 文档,在接口没有开发出来之前,要进行接口的测试,只能本地或者通过一些平台(比如 rap)去模拟接口生成相关数据,这对于前端开发人员来说也是一个额外的负担。

视频介绍

JApiDocs 可以以非常优雅的方式帮助 Java 程序员解决上面的问题,让 API 文档这件重要的"小事"不再是一种负担,尤其你如果是用 spring bootplay framework 或者 jfinal 的话,你会尤其感受到它的友好。尤其是小步快跑的小团队,希望 Ta 可以帮你们赢得一些时间。

本来想用图文的形式,后来灵感一现,何不用一个简短的视频呢?直接明了,所以硬着头皮第一次录了个视频,恶心的优酷有广告,视频时长3分30秒,不会浪费大家很多时间: 点击查看

和其他工具的对比

JApiDocs 和 swaggerapidocjs 有什么区别呢?这里我无意见看到 github 上网友的提的一个 issue ,大家可以感受一下:

这两天把想集成的 rap 功能做好了,终于可以自恋的总结了一下:

API 工具 文档支持 语言支持 接口测试
swagger 功能强大,学习成本高,维护成本高 多语言 支持
apidocjs 学习成本一般,维护成本高 多语言 不支持
JApiDocs 代码即文档,学习和维护成本低 Java 支持发布到 RAP

对于 Java 程序员来说,JApiDocs 作为一个衔接前后端开发的的工具,尽可能把重复劳动都自动化了,实现了代码即文档,持续集成接口测试的小目标。反正它已经成为我的首选 API 文档工具了,我希望也可以成为你的首选。

如何开始

项目地址:https://gitee.com/yeguozhong/JApiDocs,目前用不到,可以先点个星星收藏起来哇。

如果你以前已经在用其他的了,积重难返,我建议你还是用以前的工具;如果你还是手工去创建文档,或者要做一个新的项目,我墙裂建议你马上开始使用 JApiDocs,记得先看文档,运行一下测试用例,5分钟就能从入门到爱不释手~ 有问题欢迎反馈,我会第一时间积极响应。交流反馈Q群:70948803

叶大侠

叶大侠

粉丝 63
博文 45
码字总数 69522
作品 5
广州
程序员
私信 提问
加载中
此博客有 3 条评论,请先登录后再查看。
干掉 Swagger,试试这个!

点击上方“朱小厮的博客”,选择“设为星标” 后台回复"加群",加入新技术 JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。 编写和维护API文档这个事情,对于后端程序员...

朱小厮
06/15
0
0
还在用Swagger(丝袜哥)生成接口文档?我推荐你试试它.....

JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后...

osc_1c2nc3bj
06/17
23
0
还在用Swagger(丝袜哥)生成接口文档?我推荐你试试它.....

JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又不得不做的事情,我们都不喜欢写文档,但除非项目前后...

java欧巴CGr
06/16
0
0
Swagger之外的选择

今天给大家安利一款接口文档生成器——JApiDocs。 swagger想必大家都用过吧,非常方便,功能也十分强大。如果要说swaager有什么缺点,想必就是注解写起来比较麻烦。如果我说有一款不用写注解...

osc_9belkob6
06/23
18
0
Swagger之外的选择

今天给大家安利一款接口文档生成器——JApiDocs。 swagger想必大家都用过吧,非常方便,功能也十分强大。如果要说swaager有什么缺点,想必就是注解写起来比较麻烦。如果我说有一款不用写注解...

Java旅途
06/22
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Free RTOS学习随笔(1),临界区代码

Free RTOS学习随笔(1),临界区代码 基本介绍 Free RTOS中临界区代码常用函数 任务级临界代码保护 调用方式 实现原理 中断级临界代码保护 调用方式 实现原理 基本介绍 临界区代码指的是那些...

osc_ho8dcqsx
30分钟前
5
0
STM32单片机驱动步进电机—简单篇

STM32单片机驱动步进电机(一) 驱动电机运动 软件:Keil5 设备:步进电机(17HS4401)、驱动器、单片机(STM32F103) 接线方式: 电机与驱动器:黑A+,绿A-,红B+,蓝B- 驱动器与单片机:M...

osc_2qah5avr
31分钟前
18
0
龙芯开源社区上线.NET主页

龙芯团队从2019年7 月份开始着手.NET Core的MIPS64支持研发,经过将近一年的研发,在2020年6月18日完成了里程碑性的工作,在github CoreCLR 仓库:https://github.com/gsvm/coreclr, 随后受...

osc_923iryp1
33分钟前
9
0
计算机组成原理笔记(二)

我的博客: https://www.luozhiyun.com/ 浮点数和定点数 我们先来看一个问题,在Chrome浏览器里面通过开发者工具,打开浏览器里的Console,在里面输入“0.3 + 0.6”: >>> 0.3 + 0.60.8999...

osc_1psr53ow
33分钟前
19
0
Vue PDF文件预览vue-pdf

最近做项目,遇到预览PDF这个功能,在网上找了找,大多推荐的是pdf.js,不过在Vue中还是想偷懒直接npm组件,最后找到了一个还不错的Vue-pdf 组件,GitHub地址:https://github.com/FranckFreiburge...

osc_1i3ltp99
34分钟前
5
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部