0

I would like to be able to document the dependencies of my services directly in my code, using Java annotations. Those annotations could bear the information about the target system, whether the connection is incoming/outgoing/2-ways, and the type of connection (REST, RabbitMQ...).

It could look like this:

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

The idea would be to generate a DOT file from all the annotations inside the project.

I have a fair idea on how to create my own annotation, with the required attributes. However, i am not sure at which part of the lifecycle of the compilation/processing i should handle those annotations.

I understand that the annotation processors generate source files, but in my case the generated files are not at all required by the compiler nor the application itself.

Ideally i would like to be able to trigger the annotation processing, and DOT file generation, by a dedicated Maven or Gradle task.

Is it something that is easily doable when writing my own annotations?

gotson
  • 3,613
  • 1
  • 23
  • 40
  • 1
    Yes, you can write your own annotation processor [AnnotationProcessing101](http://hannesdorfmann.com/annotation-processing/annotationprocessing101) which will process your annotation. [This](https://www.baeldung.com/java-annotation-processing-builder) is another good one, which is more basic. – Mark Nov 06 '18 at 11:25
  • 1
    You can try using `exec-maven-plugin` with `java` goal. If required, then use `build-helper-maven-plugin` to package those files as part of your application. – Sukhpal Singh Nov 06 '18 at 11:25
  • Thanks to both of you, i think i get a clearer idea. I would need as for any custom annotation the Annotation itself, and its Processor in a separate project. In addition, i could provide an implementation of the Maven or Gradle report plugin that would use my processor to generate the documentation. If people do not want to use Maven or Gradle, they can still use the Processor via `javac` by themselves. – gotson Nov 06 '18 at 11:47

2 Answers2

1

If you want to create documentation via maven than you need add the bellow two dependencies as plugins and then execute site maven goal.

        <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>

If you just want to document REST endpoints than you can use swagger. If your project uses spring than the integration of swagger is pretty easy. You can use this tutorial.

If you want to save in a file the dependency graph of your project you can simply execute the following maven command.

mvn dependency:tree -Doutput=/path/to/file
aurelius
  • 3,946
  • 7
  • 40
  • 73
  • Thanks, i know about Swagger, but i would like to generate graph files that could document any dependency, for instance if i have a Corba dependency or TibcoRV dependency. I also would like to generate documentation at compile time. The `maven-project-info-reports-plugin` looks interesting though, i will have a look into it! – gotson Nov 06 '18 at 11:43
  • Thanks, but it is not about the dependencies of my Java project either (maven or gradle dependencies), but about the external systems i connect to, in a micro-services environment for example. – gotson Nov 07 '18 at 02:41
0

Annotations are processed by the Java compiler directly.

For Maven, one can use the maven-compiler-plugin. It is also possible to perform the compilation in 2 steps, as explained here.

For Gradle, one can add the processors in the dependencies block under the annotationProcessor configuration, as explained here.

Annotation retention can be specified as SOURCE, so they won't be kept after compilation.

gotson
  • 3,613
  • 1
  • 23
  • 40