一个给 Java 程序员用的 Api 文档生成工具

api 文档做为先后端同窗的沟通桥梁，其重要性是不言而喻的。目前通用的工具备像apidoc/apidoc，caixw/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 Boot， PlayFramework，JFinal，不须要额外声明路由。
4. 支持通常的 Java Web 工程，须要在相关方法添加额外的路由。
5. 支持接口声明过期(@Deprecated)，方便的文档目录等。
6. 支持自定义代码生成模板。

5分钟集成

(1) 咱们以 spring 为例，一张图很容易就明白了 JApiDocs 是怎么工做的了，你在设计接口的时候能够顺便就把相关的注释给填好了，这和 Java 程序员的编程习惯是保持一致的。

这里你可能会对@ApiDoc注解感到迷惑，这也是惟一须要一点额外工做的地方，别急，下面立刻就讲到它。

(2) @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 框架，那么你只须要写好返回的视图模型就能够了。

(3) 你能够在项目的目录下找到有两个，一个是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);
复制代码

(4) 自定义输出 Java 和 IOS 代码：

你能够把工程里面相关的代码模板文件拷贝出来，而后在配置参数声明好该路径便可，具体的模板文件以下：

(5) 更多的用法和不一样的框架能够参考咱们的示例代码。

注意的地方

(1) 返回视图类不支持循环引用，会致使 stackoverflow。

class UserVO{
    BookVO book;
}

class BookKVO{
    UserVO user;
}
复制代码

(2) 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。你的支持是我前进的动力！

技术交流群：70948803，大部分时间群里都是安静的，只交流技术相关，不多发言，不欢迎广告喷子。