文档章节

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

叶大侠
 叶大侠
发布于 2017/08/12 09:58
字数 1487
阅读 75
收藏 1

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/创业者,欢迎加入一起交流。

二维码

© 著作权归作者所有

共有 人打赏支持
叶大侠

叶大侠

粉丝 57
博文 44
码字总数 67312
作品 5
广州
程序员
国外程序员整理的Java资源大全

构建 这里搜集了用来构建应用程序的工具。 Apache Maven:Maven使用声明进行构建并进行依赖管理,偏向于使用约定而不是配置进行构建。Maven优于Apache Ant。后者采用了一种过程化的方式进行配...

强子哥哥
2015/11/16
0
1
推荐!国外程序员整理的Java资源大全

构建 这里搜集了用来构建应用程序的工具。 Apache Maven:Maven使用声明进行构建并进行依赖管理,偏向于使用约定而不是配置进行构建。Maven优于Apache Ant。后者采用了一种过程化的方式进行配...

huntering
2015/01/13
0
0
推荐!国外程序员整理的Java资源大全

Java 几乎是许多程序员们的入门语言,并且也是世界上非常流行的编程语言。国外程序员 Andreas Kull 在其 Github 上整理了非常优秀的 Java 开发资源,推荐给大家。 译文由 ImportNew- 唐尤华翻...

李朝强
2015/11/21
0
0
外国程序员整理的Java资料大全

构建 这里搜集了用来构建应用程序的工具。 Apache Maven:Maven使用声明进行构建并进行依赖管理,偏向于使用约定而不是配置进行构建。Maven优于Apache Ant。后者采用了一种过程化的方式进行配...

乔三爷
2015/03/30
0
1
[转]不走弯路,就是捷径??Java 学习之路

0.引言 软件开发之路是充满荆棘与挑战之路,也是充满希望之路。Java学习也是如此,没有捷径可走。梦想像《天龙八部》中虚竹一样被无崖子醍醐灌顶而轻松获得一甲子功力,是很不现实的。每天仰...

Eagleguo998
2010/07/20
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

[MicroPython]STM32F407开发板驱动OLED液晶屏

1.实验目的 1.学习在PC机系统中扩展简单I/O 接口的方法。 2.进一步学习编制数据输出程序的设计方法。 3.学习 F407 Micropython开发板控制OLED显示字符。 2.所需元器件 F407 Micropython开发板...

bodasisiter
20分钟前
0
0
php require和include 相对路径一个有趣的坑

以前总是被教育,不要使用相对路径,这样性能比较差,但是相对路径的问题不仅仅是性能哦,看下面这里例子 这是项目结构 .├── main.php├── t│ ├── t1.php│ └── t2.php└─...

anoty
20分钟前
9
0
x64技术之SSDT_Hook

测试环境: 虚拟机: Windows 7 64bit 过PG工具 驱动加载工具 PCHunter64 系统自带的计算器和任务管理器等 实现思路: 实际思路与win32的思路一样.都是替换SSDT表里边的函数地址.不过微软被搞怕...

simpower
22分钟前
0
0
TreeMap源码分析,看了都说好

一、简介 TreeMap最早出现在JDK 1.2中,是 Java 集合框架中比较重要一个的实现。TreeMap 底层基于红黑树实现,可保证在log(n)时间复杂度内完成 containsKey、get、put 和 remove 操作,效率很...

Java小铺
32分钟前
0
0
协变、逆变

概念 假设 A、B表示类型 ≤ 表示继承关系 f<⋅>表示类型转换 若A ≤ B,则 A是B的子类,B是A的超类 协变、逆变 什么是型变?型变(type variance)允许对类型进行子类型转换。 为了下面讲解先...

obaniu
38分钟前
0
0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部