文档章节

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

叶大侠
 叶大侠
发布于 2017/08/18 12:43
字数 1264
阅读 884
收藏 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

© 著作权归作者所有

共有 人打赏支持
叶大侠

叶大侠

粉丝 57
博文 44
码字总数 67312
作品 5
广州
程序员
加载中

评论(2)

叶大侠
叶大侠

引用来自“红薯”的评论

url 不换成码云的啊?:)

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

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

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

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

叶大侠
04/15
0
0
安卓手机上 K 歌,声音延迟怎么解决?

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

编辑部的故事
07/16
0
0
【开源访谈】程序员,希望你不是狼,也不是小白兔

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

h4cd
08/05
0
0
Windows下mock环境搭建-加速项目Api开发

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

liuzxgeek
2016/10/13
0
0

没有更多内容

加载失败,请刷新页面

加载更多

Spring IOC实现原理

1、BeanDefinition 对依赖翻转模式中管理对象依赖关系的数据抽象 实现依赖翻转功能的核心数据结构 依赖翻转功能都是围绕对BeanDefinition 处理完成的 有了这些BeanDefinition 基础数据结构,...

职业搬砖20年
15分钟前
0
0
Python判断变量的数据类型的两种方法

1、isinstance(变量名,类型) def varargsql(self, sql, *args): if isinstance(args, tuple): self.cursor.execute(sql, args) self.conn.commit() 2、通过与其他已......

fang_faye
16分钟前
0
0
xml 转义特殊字符

XML中共有5个特殊的字符,分别是:&<>“’。如果配置文件中的注入值包括这些特殊字符,就需要进行特别处理。有两种解决方法:其一,采用本例中的特殊标签,将包含特殊字符的字符串封装起来;...

inidcard
17分钟前
0
0
Mysql中哪些sql 不会走索引

1. 索引列参与了计算 SELECT `sname` FROM `stu` WHERE `age`+10=30; 2. 索引使用了函数运算 SELECT `sname` FROM `stu` WHERE LEFT(`date`,4) <1990; 3. like SELECT * FROM `houdunwang` W......

ChyiHuang
26分钟前
1
0
nginx 504 Gateway Time-out

打开nginx.config: 参数介绍: #设定http服务器http{include mime.types; #文件扩展名与文件类型映射表default_type application/octet-stream; #默认文件类型#charset utf-8; #默...

lyle_luo
28分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部