文档章节

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

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

我的博客原文

背景介绍

一般公司的开发流程应该是这样的,产品评估会议完了之后,接着就是各就位的设计,开发了,当然这个过程中会有一些反复的交叉。我们这里主要讨论在评估完成之后,原型交给开发的这个节点。在这个节点上,如果没有接口文档,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

© 著作权归作者所有

共有 人打赏支持
叶大侠

叶大侠

粉丝 59
博文 44
码字总数 67312
作品 5
广州
程序员
私信 提问
加载中

评论(2)

叶大侠
叶大侠

引用来自“红薯”的评论

url 不换成码云的啊?:)

回复@红薯 : 改~~
红薯
红薯
url 不换成码云的啊?:)
JApiDocs 1.2.2 发布,Java 高效 Api 文档生成工具

软件简介: JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性,你只管用心设计好接口,添加必要的注释,JApiDocs 会帮你导出一份漂亮的 Html 接口文档...

叶大侠
09/23
0
0
JApiDocs 1.2 版本发布,高效 API 文档生成工具

软件简介: JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性,你只管用心设计好接口,添加必要的注释,JApiDocs 会帮你导出一份漂亮的 Html 接口文档...

叶大侠
04/15
0
0
【开源访谈】程序员,希望你不是狼,也不是小白兔

1、焦虑 第一批 90 后已经老了 第一批 90 后已经出家了 第一批 90 后已经离婚了 摩拜创始人套现 15 亿:你的同龄人,正在抛弃你 年薪 200 万的人被裁掉了,月薪 5000 的你该怎么办? 你以为你...

h4cd
08/05
0
0
安卓手机上 K 歌,声音延迟怎么解决?

这篇文章可以为你提供一个解决录音和播放同步问题的思路,而且解决了声音从手机传输到耳机上有延时的问题。 初识音频 在开始之前,我先简单介绍一下音频相关的基础知识,方便下文理解。 我们...

编辑部的故事
07/16
0
0
Windows下mock环境搭建-加速项目Api开发

本文来自http://blog.csdn.net/liuxian13183/ ,引用必须注明出处! 公司进行技术部拆分,以项目制作为新的开发模式,前端+移动端+后端,于是加速Api开发变得很有必要,准备使用mock加速进程...

liuzxgeek
2016/10/13
0
0

没有更多内容

加载失败,请刷新页面

加载更多

利用cefSharp实现网页自动注册登录的需要注册的一些事项

最近朋友有个需要自动注册登录点击的事,我帮着写了写,好久没写过这东西了,在写的过程中总结了需要注意的一些事项。 一、换IP之后要测试一下速度,我目前用的最简单的测试方法就是20-30秒加...

我退而结网
18分钟前
1
0
Go语言中使用 BoltDB数据库

boltdb 是使用Go语言编写的开源的键值对数据库,Github的地址如下: https://github.com/boltdb/bolt boltdb 存储数据时 key 和 value 都要求是字节数据,此处需要使用到 序列化和反序列化。...

Oo若离oO
18分钟前
1
0
zookeeper分布式锁

//lock 锁 定义分布式锁public interface Lock {//获取锁public void getLock();//释放锁public void unLock();} public abstract class ZookeeperAbstractLock implements Loc......

熊猫你好
25分钟前
0
0
mysql_事务隔离机制

事务隔离机制 事务就是要保证一组数据库操作,要么全部成功,要么全部失败。在mysql中,事务支持是在引擎层实现的。mysql是一个支持多引擎的系统,但并不是所有引擎都支持事务,比如mysql...

grace_233
28分钟前
0
0
不学无数——Java中IO和NIO

JAVA中的I/O和NIO I/O 问题是任何编程语言都无法回避的问题,可以说 I/O 问题是整个人机交互的核心问题,因为 I/O 是机器获取和交换信息的主要渠道。在当今这个数据大爆炸时代,I/O 问题尤其...

不学无数的程序员
34分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部