文档章节

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

叶大侠
 叶大侠
发布于 2017/08/18 12:43
字数 1264
阅读 802
收藏 58
点赞 0
评论 2

我的博客原文

背景介绍

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

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

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

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

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

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

liuzxgeek
2016/10/13
0
0
叶大侠/JApiDocs

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

叶大侠
2017/08/12
0
0
【FPGA-F3】阿里云FAAS平台,极大简化FPGA开发部署流程

FPGA (现场可编程门阵列)由于其硬件并行加速能力和可编程特性,在传统通信领域和IC设计领域大放异彩。一路走来,FPGA的技术并不是一个新兴的硬件器件,由于其开发门槛过高,硬件加速算法的发...

孟蓁蓁
05/10
0
0
Java 的 Api 文档生成工具--JApiDocs

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

叶大侠
2017/08/11
542
2
Web研发模式演变史

前不久徐飞写了一篇很好的文章:Web 应用的组件化开发。本文尝试从历史发展角度,说说各种研发模式的优劣。 一、简单明快的早期时代 可称之为 Web 1.0 时代,非常适合创业型小项目,不分前后...

ingarfield_123
2014/06/12
0
0
Web前后分离架构研发模式de演变

前不久徐飞技术博客写了一篇很好的文章:Web 应用的组件化开发。本文尝试从历史发展角度,说说各种研发模式的优劣。 一、简单明快的早期时代 可称之为 Web 1.0 时代,非常适合创业型小项目,...

English0523
2015/09/30
0
0
Web 研发模式演变

作者:lifesinger 前不久徐飞写了一篇很好的文章:Web 应用的组件化开发。本文尝试从历史发展角度,说说各种研发模式的优劣。 一、简单明快的早期时代 可称之为 Web 1.0 时代,非常适合创业型...

首席安全砖家
2014/05/08
331
1
Web研发模式演变史,重新理解WEB架构

前不久徐飞写了一篇很好的文章:Web 应用的组件化开发。本文尝试从历史发展角度,说说各种研发模式的优劣。 一、简单明快的早期时代 可称之为 Web 1.0 时代,非常适合创业型小项目,不分前后...

YOTOO
2014/04/24
0
1

没有更多内容

加载失败,请刷新页面

加载更多

下一页

流利阅读笔记29-20180718待学习

高等教育未来成谜,前景到底在哪里? Ray 2018-07-18 1.今日导读 在这个信息爆炸的年代,获取知识是一件越来越容易的事情。人们曾经认为,如此的时代进步会给高等教育带来众多便利。但事实的...

aibinxiao
13分钟前
6
0
第15章FTP服务搭建与配置

15.1FTP介绍 FTP多用于Windows传文件到linux rz sz在文件超过4G,就无法使用了——>安装包yum install -y install lrzsz rz把 window 上的文件传输到 linux 上 sz 把 linux 上的文件传输到 ...

Linux学习笔记
21分钟前
0
0
OSChina 周三乱弹 —— 你被我从 osc 老婆们名单中踢出了

Osc乱弹歌单(2018)请戳(这里) 【今日歌曲】 @小鱼丁:分享五月天的单曲《后来的我们 (电影《后来的我们》片名曲)》: 《后来的我们 (电影《后来的我们》片名曲)》- 五月天 手机党少年们想...

小小编辑
25分钟前
6
1
Spring Boot Admin 2.0开箱体验

概述 在我之前的 《Spring Boot应用监控实战》 一文中,讲述了如何利用 Spring Boot Admin 1.5.X 版本来可视化地监控 Spring Boot 应用。说时迟,那时快,现在 Spring Boot Admin 都更新到 ...

CodeSheep
44分钟前
0
0
Python + Selenium + Chrome 使用代理 auth 的用户名密码授权

米扑代理,全球领导的代理品牌,专注代理行业近十年,提供开放、私密、独享代理,并可免费试用 米扑代理官网:https://proxy.mimvp.com 本文示例,是结合米扑代理的私密、独享、开放代理,专...

sunboy2050
今天
0
0
实现异步有哪些方法

有哪些方法可以实现异步呢? 方式一:java 线程池 示例: @Test public final void test_ThreadPool() throws InterruptedException { ScheduledThreadPoolExecutor scheduledThre......

黄威
今天
1
0
linux服务器修改mtu值优化cpu

一、jumbo frames 相关 1、什么是jumbo frames Jumbo frames 是指比标准Ethernet Frames长的frame,即比1518/1522 bit大的frames,Jumbo frame的大小是每个设备厂商规定的,不属于IEEE标准;...

六库科技
今天
0
0
牛客网刷题

1. 二维数组中的查找(难度:易) 题目描述 在一个二维数组中(每个一维数组的长度相同),每一行都按照从左到右递增的顺序排序,每一列都按照从上到下递增的顺序排序。请完成一个函数,输入...

大不了敲一辈子代码
今天
0
0
linux系统的任务计划、服务管理

linux任务计划cron 在linux下,有时候要在我们不在的时候执行一项命令,或启动一个脚本,可以使用任务计划cron功能。 任务计划要用crontab命令完成 选项: -u 指定某个用户,不加-u表示当前用...

黄昏残影
昨天
0
0
设计模式:单例模式

单例模式的定义是确保某个类在任何情况下都只有一个实例,并且需要提供一个全局的访问点供调用者访问该实例的一种模式。 实现以上模式基于以下必须遵守的两点: 1.构造方法私有化 2.提供一个...

人觉非常君
昨天
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部