javadoc生成文档API以及解决lombok注解没有字段生成问题

将Lombok注解应用到一个项目中可以大大减少在IDE中生成或手工编写的样板代码行数。
这样可以减少维护开销，减少bug，提高类的可读性。

在idea中要使用lombok是很简单的事情，只需要安装一个lombok plugin，然后在pom.xml加入对lombok的依赖即可。

			<dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.4</version>
            </dependency>

与任何技术选择一样，使用Lombok既有积极的作用，也会有消极的影响。而最典型的不好的一面就是，将源代码生成javadoc的时候，因为源码里边使用了lombok，只声明了private的属性，而未编写setter/getter方法等，最后生成的文档当然就不会包含这些属性的getter和setter方法。先通过一个简单的例子复现一下这个场景。

一、问题重现
要用idea生成javadoc，需要引入javadoc的plugin，在pom.xml中加入引入即可。详情可参见官网。

1、我们用idea创建一个lombok的示例项目，pom.xml是这样的：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
 
    <groupId>com.dengxiaolong</groupId>
    <artifactId>lombok</artifactId>
    <version>1.0.0</version>
 
    <dependencies>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.2</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
 
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

利用lombok定义一个简单的DTO类如下：

package com.dengxiaolong.lombok;
import lombok.Data;
@Data
public class FooDto {
private int id;
private String name;
private String email;
}

2、引入依赖后，点击idea的右侧，就可以看到javadoc的相关命令了。我们双击执行”javadoc:javadoc”这个命令即可。

执行完成后，会在项目的target/site/apidocs/目录重生成javadoc。点击查看会发现GiftVo类中的字段id、name、email都没有出现在javadoc中。

二、成本和收益
对于Lombok的成本和收益，在Lombok的官网的文章中，做了详细地介绍，为了解决Lombok带来的问题，官方也提供了相应的***解决方案——delombok***，它的作用就是将Lombok的注解还原成等效的源代码。可以通过命令行使用：

java -jar lombok.jar delombok src -d src-delomboked

当然，也可以通过ant任务来实现。不过，本文要探讨的还是基于idea来解决这个问题。

使用delombok
既然提供了delombok，那么我们就可以考虑通过它来生成源代码，然后再想办法让javadoc来通过源代码的目录生成javadoc，这样我们就能一方面享受lombok的好处，一方面又能避免它带来的问题了。

至此，我们可以这样来完成我们的目标了：

1、要使用delombok，我们需要配置一个lombok的maven插件到pom.xml：

<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok-maven-plugin</artifactId>
            <version>1.18.0.0</version>
            <configuration>
                <encoding>UTF-8</encoding>
                <sourceDirectory>src/main/java</sourceDirectory>
            </configuration>
        </plugin>
  </plugins>
</build>
 

2、在右侧Maven Projects里边找到”lombok:delombok”的任务，双击执行。执行成功后，会在target/generated-sources/delombok目录生成的等效源代码。

3、修改javadoc的源代码目录
delombok生成了一份新的等效源代码后，我们就需要修改javadoc的源代码的目录了，同使用lombok的插件一样，我们只需要在配置里边增加sourcepath的配置项即可。

sourcepath用来指定查找源文件(.java)的搜索路径，可以通过用冒号(:)分隔多个路径。

        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.1</version>
            <configuration>
                <sourcepath>target/generated-sources/delombok</sourcepath>
            </configuration>
        </plugin>
       ...

4、然后，我们再通过右侧的Maven Projects执行javadoc:javadoc命令即可生成我们需要的javadoc文档了。

打开index.html

经过上面delombok和javadoc对于源代码目录的巧妙组合，我们一方面减少了开发时的代码量，另一方面也能保证javadoc生成的文档的完整性。这样一来，lombok就是非常完美的工具了。