SpringBoot使用JApiDocs生成API接口文档初体验

目前项目中使用的是rap2来做API接口文档管理，但是说实话这东西和写doc版的接口文档没太大区别，接口变动时还是得修改代码和rap2上的接口定义，当初也考虑过swagger，但是swagger的代码入侵性太强所以放弃。今天在一个公众号上看到一篇文章说JApiDocs相比于swagger来说，无需任何代码入侵就能生成接口文档，这个特性立马让我有了试一试的冲动。

官方文档中说它是直接解析SpringBoot的源码获取注释和参数类型，所以无需在接口上增加任何代码，只需要在SpringBoot的启动类中加上一个配置代码。话不多说，立马用起来！

首先加上maven依赖。

        <dependency>
            <groupId>io.github.yedaxia</groupId>
            <artifactId>japidocs</artifactId>
            <version>1.3</version>
        </dependency>

然后在SpringBoot的main方法中加入以下配置代码。

DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 项目根目录
config.setProjectName("ProjectName"); // 项目名称
config.setApiVersion("V1.0");       // 声明该API的版本
config.setDocsPath("your api docs path"); // 生成API 文档所在目录
config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
Docs.buildHtmlDocs(config); // 执行生成文档

注意，这里有第一个坑，setProjectPath这个里面官方写的是参数是项目根目录，但是我填入SpringBoot工程的根目录时生成出来的接口是空的，也就是说它根本没有找到接口所在的类。然后网上也搜不到什么有关的信息，于是我试了下指定为SpringBoot工程的根目录下的src目录，结果果然生成成功了。

还有一点需要注意的是，这个工具必须所有的接口参数与返回值是本工程内定义的pojo，不能是jar包中的类，不然就会报错，这一点官方文档中说的很清楚，但是有一个坑是，使用Java自带的Object类作为接口返回类型也是不行的！而String是可以的！这个有点无语。官方说明如下：

我们知道，经过编译后的 class 字节码中是没有注释信息的，如果要通过反射字节码的方式来实现，则不可避免要引入运行时注解，这样会增加使用成本， 考虑到这一点，JApiDocs 从第二个版本之后就改成了使用解析源码的方式，而不是反射字节码的思路来实现了，但这样直接导致的缺陷就是： 所有的 Form Bean (表单)对象和返回对象就必须在项目的源码中，否则就无法解析了，如果你们项目的JavaBean对象是通过jar包的形式提供的， 那很遗憾，JApiDocs将无法支持。

总体来说简单的项目使用这个还是不错的，但是大点的项目就不太适合了，因为大点的项目的一些返回类型都封装在common中作为jar引入到各个项目了，所以也就用不了了。这个是目前这个工具最大的痛点，希望以后有可能解决吧