生成文档的 Java 注释的哪个生命周期？答案

【问题标题】：Which lifecycle for a Java annotation that generates documentation?生成文档的 Java 注释的哪个生命周期？
【发布时间】：2018-11-06 11:20:07
【问题描述】：

我希望能够使用 Java 注释直接在我的代码中记录我的服务的依赖关系。这些注解可以承载目标系统的信息，连接是传入/传出/2路，以及连接类型（REST、RabbitMQ...）。

它可能看起来像这样：

@Dependency(target = "Twitter API", type = "Outgoing", medium = "REST")

这个想法是从项目内的所有注释中生成DOT file。

我对如何使用所需属性创建自己的注释有一个很好的想法。但是，我不确定我应该在编译/处理生命周期的哪个部分处理这些注释。

我了解注释处理器会生成源文件，但在我的情况下，编译器或应用程序本身根本不需要生成的文件。

理想情况下，我希望能够通过专用的 Maven 或 Gradle 任务触发注释处理和 DOT 文件生成。

写自己的注解是不是很容易做到？

【问题讨论】：

是的，您可以编写自己的注释处理器AnnotationProcessing101，它将处理您的注释。 This 是另一个不错的，比较基础的。
您可以尝试使用exec-maven-plugin 和java 目标。如果需要，然后使用 build-helper-maven-plugin 将这些文件打包为您的应用程序的一部分。
感谢你们两位，我想我有了更清晰的想法。对于任何自定义注释，我都需要注释本身，以及它的处理器在一个单独的项目中。此外，我可以提供 Maven 或 Gradle 报告插件的实现，该插件将使用我的处理器来生成文档。如果人们不想使用 Maven 或 Gradle，他们仍然可以通过javac 自己使用处理器。

标签： java annotations

【解决方案1】：

如果您想通过 maven 创建文档，则需要添加以下两个依赖项作为插件，然后执行 site maven 目标。

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.7.1</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-project-info-reports-plugin</artifactId>
            <version>3.0.0</version>
        </plugin>

如果您只想记录 REST 端点，则可以使用 swagger。如果你的项目使用 spring，那么集成 swagger 就很容易了。你可以使用this教程。

如果您想将项目的依赖关系图保存在文件中，您只需执行以下 maven 命令即可。

mvn dependency:tree -Doutput=/path/to/file

【讨论】：

谢谢，我知道 Swagger，但我想生成可以记录任何依赖项的图形文件，例如，如果我有 Corba 依赖项或 TibcoRV 依赖项。我也想在编译时生成文档。 maven-project-info-reports-plugin 看起来很有趣，我会看看它！
谢谢，但这也不是关于我的 Java 项目的依赖项（maven 或 gradle 依赖项），而是关于我连接到的外部系统，例如在微服务环境中。

【解决方案2】：

注解由 Java 编译器直接处理。

对于Maven，可以使用maven-compiler-plugin。也可以分两步执行编译，如here 所述。

对于Gradle，可以在annotationProcessor 配置下的dependencies 块中添加处理器，如here 所述。

注解retention可以指定为SOURCE，编译后不会保留。

【讨论】：