文档章节

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

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

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

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

叶大侠
2018/04/15
1K
0
广州源创会图文回顾,大漠穷秋现身分享Angular

2017年广州源创会于8月19日圆满落幕,查看本次活动详情请点击这里,广州站所有PPT查看文末下载链接。 与往年选择年末来广州不同的是,今年的广州站来的更早一点,对于南方来说依然是酷暑的八...

Alaise
2017/08/21
897
8
安卓手机上 K 歌,声音延迟怎么解决?

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

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

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

h4cd
2018/08/05
5.2K
9

没有更多内容

加载失败,请刷新页面

加载更多

安卓constraintLayout中app:srcCompat设置的图片显示不出来

使用 app:srcCompat 的时候 引入的图片显示不出来的解决方案 首先查看的你的Activity 继承的是那个Activity 如果是继承AppcompatActivity 使用 ImageView的 app:srcCompat 是没有问题的 如果...

雨焰
41分钟前
1
0
MySQL mysqldump数据导出详解

MySQL mysqldump数据导出详解 2016-04-07 11:14 by pursuer.chen, 114348 阅读, 0 评论, 收藏, 编辑 介绍 在日常维护工作当中经常会需要对数据进行导出操作,而mysqldump是导出数据过程中使用...

linjin200
41分钟前
0
0
Lucene 检索时的步骤

用户输入查询语句:lucene AND learned NOT hadoop 搜索主要分为以下几步 第一步、对查询语句进行词法分析,语法分析,及语言处理 词法分析主要用来识别单词和关键字 语法分析主要是根据查询...

kdy1994
42分钟前
2
0
Gradle Implementation vs API configuration

注: 可以把 Implementation理解为java类的private, 使用Implementation则外部依赖本库的代码引用不到本库Implementation的代码, 也就是降低依赖树的层级, 这样就可以避免外部代码编译时候, 导...

SuShine
46分钟前
2
0
pdf安卓手机适配以及ie的兼容 以及隐藏掉下载打印按钮的方式

这是我目前遇到pdf方面最多的问题。 在百度上搜了很多答案,结果都是建议使用插件。而目前百度能搜的插件基本上都是有缺陷的。自己测试了很多插件。最后使用了pdf.js这个插件。这个插件目前完...

流年那么伤
52分钟前
1
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部