Myujth

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?

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

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.