文档章节

Java 程序员高效 Api 文档生成工具

叶大侠
 叶大侠
发布于 2017/08/12 09:58
字数 1487
阅读 67
收藏 1
点赞 0
评论 0

api 文档作为前后端同学的沟通桥梁,其重要性是不言而喻的。目前通用的工具有像apidoc/apidoccaixw/apidoc这样的第三方库,虽然具有语言无关的特性,但是真正用起来额外多了很多工作量,而且维护起来麻烦,这也是笔者设计和开发这个工具的原因,想通过 java 本身的语言特性和结合强大的 IDE ,使得生成和维护 api 文档这件事情变的自然而美好。

简介

github地址:JApiDocs

JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性,你只管用心设计好接口,添加必要的注释,JApiDocs 会帮你导出一份漂亮的 Html 文档,并生成相关的 Java 和 Object-C 相关数据模型代码,从此,Android 和 IOS 的同学可以少敲很多代码了,你也不需要费力维护接口文档的变化,只需要维护好你的代码就可以了。

特性

  1. 以一个 Controller 作为一组接口导出到一个 Html 文件中。
  2. 支持生成 Java 和 Object-C 语言的 Response 模型代码。
  3. 深度支持 Spring BootPlayFrameworkJFinal,不需要额外声明路由。
  4. 支持一般的 Java Web 工程,需要在相关方法添加额外的路由。
  5. 支持接口声明过时(@Deprecated),方便的文档目录等。
  6. 支持自定义代码生成模板。

5分钟集成

  1. 我们以 spring 为例,一张图很容易就明白了 JApidocs 是怎么工作的了,你在设计接口的时候可以顺便就把相关的注释给填好了,这和 Java 程序员的编程习惯是保持一致的。

spring controller

这里你可能会对@ApiDoc注解感到迷惑,这也是唯一需要一点额外工作的地方,别急,下面马上就讲到它。

  1. @ApiDoc 是我们定义的一个注解,除非程序运行起来,否则我们是没办法知道 response 里面都包含有哪些内容,但是我们明明有了相关的视图类,为了解决这个问题,我们折衷设计了这个基于RetentionPolicy.SOURCE的注解,它不会给现有的代码造成任何的负担。由于是基于 Java 源码进行解析的,所以你不需要依赖我们的 Jar 包,你可以在你自己的工程任意地方添加这个简单的类即可,当然,如果你连这个也不愿意也是没关系的,你只需要直接添加我们的 Jar 包即可,里面已经为你准备好这个类了。

@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.METHOD})
public @interface ApiDoc {

    /**
     * result class
     * @return
     */
	Class<?> value() default Null.class;

    /**
     * result class
     */
	Class<?> result() default Null.class;

    /**
     * request url
     */
	String url() default "";

    /**
     * request method
     */
	String method() default "get";

    final class Null{

    }
}

如果你用的是我们深度支持的 MVC 框架,那么你只需要写好返回的视图模型就可以了。

  1. 你可以在项目的目录下找到有两个,一个是all结尾的,里面包含了第三方的依赖包,一个是min结尾的,不含第三方的依赖包。

命令行模式:

下载all包,然后在和这个jar包相同目录下创建名称是docs.config的配置文件,里面可以配置这几个参数:

projectPath = 工程目录(必须)
docsPath = 文档输出目录(非必须,默认是${projectPath}/apidocs)
codeTplPath = 代码模版目录 (非必须,如果你需要自定义生成的代码才会用到。)
mvcFramework = [spring, play, jfinal, generic](非必须,代码内部有判断,如果出现误判的情况,可以通过这个强制指定)

配置好之后,运行该jar包就可以了。

java -jar ***-all.jar

代码模式

如果想做一些持续集成的话,代码模式还是比较方便的,根据你的需要可以选择all包或者min包,相关第三方依赖如下:

compile 'com.google.code.gson:gson:2.8.0'
compile 'com.github.javaparser:javaparser-core:3.3.0'

只需要调用下面一句代码即可:

Docs.buildHtmlDocs(DocsConfig config);
  1. 自定义输出 Java 和 IOS 代码:

你可以把工程里面相关的代码模板文件拷贝出来,然后在配置参数声明好该路径即可,具体的模板文件如下: code template files

  1. 更多的用法和不同的框架可以参考我们的示例代码。

注意的地方

  1. 返回视图类不支持循环引用,会导致 stackoverflow。
class UserVO{
    BookVO book;
}

class BookKVO{
    UserVO user;
}
  1. JFinal 路由配置必须在 configRoute 方法体里,否则会解析失败。
    @Override
    public void configRoute(Routes me) {
        me.add("/api/v1/user", UserController.class);
        me.add("/api/v1/book", BookController.class);
        me.add(new AmdinRoutes());
    }

支持和反馈

由于每个人写代码的习惯可能都不一样,虽然已经尽可能考虑到了多种不同的情况,但由于作者本人的认知和精力有限,难免会疏忽或者本身就存在有 bug 的情况,如果你在使用的过程中有碰到困难或者疑问,欢迎提issue或者加扣扣群进行反馈:70948803。

如果你觉得这个项目对你有用,请猛戳 star。你的支持是我前进的动力!

另外,我创建了一个微信群,用于探讨如何用技术去创收,如果你是有经验的程序/设计师/PM/创业者,欢迎加入一起交流。

二维码

© 著作权归作者所有

共有 人打赏支持
叶大侠

叶大侠

粉丝 56
博文 44
码字总数 67312
作品 5
广州
程序员
JApiDocs 1.2 版本发布,高效 API 文档生成工具

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

叶大侠 ⋅ 04/15 ⋅ 0

4个Java的常用工具,了解一下吧!

在现如今的互联网时代里,Java无疑是一种极为流行的开发语言,无论是程序界还是整个互联网行业势必带来很大的影响。不管是人才需求还是薪资水平上,Java的发展前景都是很乐观的。 关于Java的...

梦想远方_8e96 ⋅ 06/15 ⋅ 0

Java 5 、6、 7中新特性

JDK5新特性(与1.4相比)【转】 1 循环 for (type variable : array){ body} for (type variable : arrayList){body} 而1.4必须是: for (int i = 0; i < array.length; i++){ type variabl......

thinkyoung ⋅ 2014/10/14 ⋅ 0

JDK 11 特性抢先看:5 月新增三个 JEP

一周前(2018年5月7日),JDK11 新增了三个 JEP 。在 jdk-dev 邮件列表中出现了三封邮件,Mark Reinhold 发表了以下公告: JDK 11 实现了 JEP:324:关于 Curve25519 和 Curve448 的重要协议...

oschina ⋅ 05/16 ⋅ 0

从Java小白到架构师必须要看的书籍,真正的“武林秘籍”!

少年,我看你骨骼精奇,将是未来万中无一的IT精英,很是适合学JAVA。维护世界和平就看你的了,我这里有能让你成为IT精英的办法!还不来看看! 基础类 1、《Thinking in Java》,入门第一位是...

启示录是真的 ⋅ 05/25 ⋅ 0

阿里年薪50WJAVA工程师转大数据学习路线!

大数据有两个方向,一个是偏计算机的,另一个是偏经济的。你学过Java,所以你可以偏将计算机的。 Java程序员想转大数据可行吗?Java是全世界使用人数最多的编程语言。不少程序员选择Java做为...

JAVA丶学习 ⋅ 04/25 ⋅ 0

分享几个JAVA程序员们最容易犯的错误,你中了几枪?

都说Java语言是一门简单的编程语言,基于C++演化而来,剔除了很多C++中的复杂特性,但这并不能保证Java程序员不会犯错。那么对于广大的Java程序员来说,它们最常犯的几个错误都是什么样的呢?...

启示录是真的 ⋅ 05/25 ⋅ 0

Java程序员必读书单,家族又添新成员

点击关注异步图书,置顶公众号 每天与你分享IT好书 技术干货 职场知识 参与文末话题讨论,每日赠送异步图书。 ——异步小编 有些革命出其不意地吸引了全世界的眼球。Twitter、Linux操作系统和...

异步社区 ⋅ 05/09 ⋅ 0

编写你的第一个HelloWorld

写在前面的话 因为Java基础是以后学习框架的基石,因此开个文集首先写写Java基础,本来想直奔基础知识的介绍,但是为了保证知识的完整性,因此从Java安装和运行“hello world”开始(虽然百度...

nanaFighting ⋅ 06/15 ⋅ 0

开源 | Eggjs 和 SOFA 的跨语言互调

SOFARPC 是近期蚂蚁金服开源的一个高可扩展性、高性能、生产级的 Java RPC 框架。在蚂蚁金服 SOFARPC 已经经历了十多年及五代版本的发展。SOFARPC 致力于简化应用之间的 RPC 调用,为应用提供...

花肉酱 ⋅ 06/14 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

Springboot2 之 Spring Data Redis 实现消息队列——发布/订阅模式

一般来说,消息队列有两种场景,一种是发布者订阅者模式,一种是生产者消费者模式,这里利用redis消息“发布/订阅”来简单实现订阅者模式。 实现之前先过过 redis 发布订阅的一些基础概念和操...

Simonton ⋅ 23分钟前 ⋅ 0

error:Could not find gradle

一.更新Android Studio后打开Project,报如下错误: Error: Could not find com.android.tools.build:gradle:2.2.1. Searched in the following locations: file:/D:/software/android/andro......

Yao--靠自己 ⋅ 昨天 ⋅ 0

Spring boot 项目打包及引入本地jar包

Spring Boot 项目打包以及引入本地Jar包 [TOC] 上篇文章提到 Maven 项目添加本地jar包的三种方式 ,本篇文章记录下在实际项目中的应用。 spring boot 打包方式 我们知道,传统应用可以将程序...

Os_yxguang ⋅ 昨天 ⋅ 0

常见数据结构(二)-树(二叉树,红黑树,B树)

本文介绍数据结构中几种常见的树:二分查找树,2-3树,红黑树,B树 写在前面 本文所有图片均截图自coursera上普林斯顿的课程《Algorithms, Part I》中的Slides 相关命题的证明可参考《算法(第...

浮躁的码农 ⋅ 昨天 ⋅ 0

android -------- 混淆打包报错 (warning - InnerClass ...)

最近做Android混淆打包遇到一些问题,Android Sdutio 3.1 版本打包的 错误如下: Android studio warning - InnerClass annotations are missing corresponding EnclosingMember annotation......

切切歆语 ⋅ 昨天 ⋅ 0

eclipse酷炫大法之设置主题、皮肤

eclipse酷炫大法 目前两款不错的eclipse 1.系统设置 Window->Preferences->General->Appearance 2.Eclipse Marketplace下载【推荐】 Help->Eclipse Marketplace->搜索‘theme’进行安装 比如......

anlve ⋅ 昨天 ⋅ 0

vim编辑模式、vim命令模式、vim实践

vim编辑模式 编辑模式用来输入或修改文本内容,编辑模式除了Esc外其他键几乎都是输入 如何进入编辑模式 一般模式输入以下按键,均可进入编辑模式,左下角提示 insert(中文为插入) 字样 i ...

蛋黄Yolks ⋅ 昨天 ⋅ 0

大数据入门基础:SSH介绍

什么是ssh 简单说,SSH是一种网络协议,用于计算机之间的加密登录。 如果一个用户从本地计算机,使用SSH协议登录另一台远程计算机,我们就可以认为,这种登录是安全的,即使被中途截获,密码...

董黎明 ⋅ 昨天 ⋅ 0

web3j教程

web3j是一个轻量级、高度模块化、响应式、类型安全的Java和Android类库提供丰富API,用于处理以太坊智能合约及与以太坊网络上的客户端(节点)进行集成。 汇智网最新发布的web3j教程,详细讲解...

汇智网教程 ⋅ 昨天 ⋅ 0

谷歌:安全问题机制并不如你想象中安全

腾讯科技讯 5月25日,如今的你或许已经对许多网站所使用的“安全问题机制”习以为常了,但你真的认为包括“你第一个宠物的名字是什么?”这些问题能够保障你的帐户安全吗? 根据谷歌(微博)安...

问题终结者 ⋅ 昨天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部