api 文档作为前后端同学的沟通桥梁，其重要性是不言而喻的。目前通用的工具有像apidoc/apidoc，caixw/apidoc这样的第三方库，虽然具有语言无关的特性，但是真正用起来额外多了很多工作量，而且维护起来麻烦，这也是笔者设计和开发这个工具的原因，想通过 java 本身的语言特性和结合强大的 IDE ，使得生成和维护 api 文档这件事情变的自然而美好。
简介
github地址：JApiDocs
JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性，你只管用心设计好接口，添加必要的注释，JApiDocs 会帮你导出一份漂亮的 Html 文档，并生成相关的 Java 和 Object-C 相关数据模型代码，从此，Android 和 IOS 的同学可以少敲很多代码了，你也不需要费力维护接口文档的变化，只需要维护好你的代码就可以了。
特性
以一个 Controller 作为一组接口导出到一个 Html 文件中。
支持生成 Java 和 Object-C 语言的 Response 模型代码。
深度支持 Spring Boot， PlayFramework，JFinal，不需要额外声明路由。
支持一般的 Java Web 工程，需要在相关方法添加额外的路由。
支持接口声明过时(
@Deprecated)，方便的文档目录等。支持自定义代码生成模板。
5分钟集成
我们以 spring 为例，一张图很容易就明白了 JApidocs 是怎么工作的了，你在设计接口的时候可以顺便就把相关的注释给填好了，这和 Java 程序员的编程习惯是保持一致的。
这里你可能会对@ApiDoc注解感到迷惑，这也是唯一需要一点额外工作的地方，别急，下面马上就讲到它。
@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 框架，那么你只需要写好返回的视图模型就可以了。
集成依赖和运行
命令行模式:
下载all包，然后在和这个jar包相同目录下创建名称是docs.config的配置文件，里面可以配置这几个参数：
projectPath = 工程目录（必须）
docsPath = 文档输出目录（非必须，默认是${projectPath}/apidocs）
codeTplPath = 代码模版目录 (非必须，如果你需要自定义生成的代码才会用到。)
mvcFramework = [spring, play, jfinal, generic](非必须，代码内部有判断，如果出现误判的情况，可以通过这个强制指定)配置好之后，运行该jar包就可以了。
java -jar ***-all.jar
代码模式
如果想做一些持续集成的话，代码模式还是比较方便的，直接添加依赖或者下载相关jar包，其中min包是不包含第三方依赖的。
compile 'io.github.yedaxia:japidocs:1.0'compile 'com.google.code.gson:gson:2.8.0'compile 'com.github.javaparser:javaparser-core:3.3.0'
只需要调用下面一句代码即可：
Docs.buildHtmlDocs(DocsConfig config);
自定义输出 Java 和 IOS 代码：
你可以把工程里面相关的代码模板文件拷贝出来，然后在配置参数声明好该路径即可，具体的模板文件如下：
更多的用法和不同的框架可以参考我们的示例代码。
注意的地方
返回视图类不支持循环引用，会导致 stackoverflow。
class UserVO{
BookVO book;
}
class BookKVO{
UserVO user;
}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，你的支持是我前进的动力！
