Which lifecycle for a Java annotation that generates documentation?

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?

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

1

Yes, you can write your own annotation processor AnnotationProcessing101 which will process your annotation. This is another good one, which is more basic.

– Mark
Nov 6 '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 6 '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.

– Gauthier
Nov 6 '18 at 11:47

add a comment |

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

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

1

Yes, you can write your own annotation processor AnnotationProcessing101 which will process your annotation. This is another good one, which is more basic.

– Mark
Nov 6 '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 6 '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.

– Gauthier
Nov 6 '18 at 11:47

add a comment |

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

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

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

java annotations

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

asked Nov 6 '18 at 11:20

Gauthier

2,3071822

1

Yes, you can write your own annotation processor AnnotationProcessing101 which will process your annotation. This is another good one, which is more basic.

– Mark
Nov 6 '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 6 '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.

– Gauthier
Nov 6 '18 at 11:47

add a comment |

1

Yes, you can write your own annotation processor AnnotationProcessing101 which will process your annotation. This is another good one, which is more basic.

– Mark
Nov 6 '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 6 '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.

– Gauthier
Nov 6 '18 at 11:47

Yes, you can write your own annotation processor AnnotationProcessing101 which will process your annotation. This is another good one, which is more basic.

– Mark
Nov 6 '18 at 11:25

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 6 '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.

– Gauthier
Nov 6 '18 at 11:47

add a comment |

2 Answers
2

active

oldest

votes

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

edited Nov 6 '18 at 12:07

answered Nov 6 '18 at 11:40

aurelius

2,05921952

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!

– Gauthier
Nov 6 '18 at 11:43

I edited my answer.

– aurelius
Nov 6 '18 at 12:08

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.

– Gauthier
Nov 7 '18 at 2:41

add a comment |

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.

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

add a comment |

Your Answer

StackExchange.ifUsing("editor", function ()
StackExchange.using("externalEditor", function ()
StackExchange.using("snippets", function ()
StackExchange.snippets.init();
);
);
, "code-snippets");

StackExchange.ready(function()
var channelOptions =
tags: "".split(" "),
id: "1"
;
initTagRenderer("".split(" "), "".split(" "), channelOptions);

StackExchange.using("externalEditor", function()
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled)
StackExchange.using("snippets", function()
createEditor();
);

else
createEditor();

);

function createEditor()
StackExchange.prepareEditor(
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: true,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: 10,
bindNavPrevention: true,
postfix: "",
imageUploader:
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
,
onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
);

);

draft saved

draft discarded

StackExchange.ready(
function ()
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53170858%2fwhich-lifecycle-for-a-java-annotation-that-generates-documentation%23new-answer', 'question_page');

);

Post as a guest

Name

Required, but never shown

2 Answers
2

active

oldest

votes

2 Answers
2

active

oldest

votes

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

edited Nov 6 '18 at 12:07

answered Nov 6 '18 at 11:40

aurelius

2,05921952

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!

– Gauthier
Nov 6 '18 at 11:43

I edited my answer.

– aurelius
Nov 6 '18 at 12:08

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.

– Gauthier
Nov 7 '18 at 2:41

add a comment |

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

edited Nov 6 '18 at 12:07

answered Nov 6 '18 at 11:40

aurelius

2,05921952

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!

– Gauthier
Nov 6 '18 at 11:43

I edited my answer.

– aurelius
Nov 6 '18 at 12:08

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.

– Gauthier
Nov 7 '18 at 2:41

add a comment |

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

edited Nov 6 '18 at 12:07

answered Nov 6 '18 at 11:40

aurelius

2,05921952

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

edited Nov 6 '18 at 12:07

answered Nov 6 '18 at 11:40

aurelius

2,05921952

edited Nov 6 '18 at 12:07

answered Nov 6 '18 at 11:40

aurelius

2,05921952

answered Nov 6 '18 at 11:40

aurelius

2,05921952

answered Nov 6 '18 at 11:40

aurelius

2,05921952

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!

– Gauthier
Nov 6 '18 at 11:43

I edited my answer.

– aurelius
Nov 6 '18 at 12:08

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.

– Gauthier
Nov 7 '18 at 2:41

add a comment |

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!

– Gauthier
Nov 6 '18 at 11:43

I edited my answer.

– aurelius
Nov 6 '18 at 12:08

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.

– Gauthier
Nov 7 '18 at 2:41

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!

– Gauthier
Nov 6 '18 at 11:43

I edited my answer.

– aurelius
Nov 6 '18 at 12:08

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.

– Gauthier
Nov 7 '18 at 2:41

add a comment |

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.

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

add a comment |

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.

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

add a comment |

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.

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

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.

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

answered Nov 13 '18 at 11:19

Gauthier

2,3071822

add a comment |

draft saved

draft discarded

Thanks for contributing an answer to Stack Overflow!

Please be sure to answer the question. Provide details and share your research!

But avoid …

Asking for help, clarification, or responding to other answers.

Making statements based on opinion; back them up with references or personal experience.

To learn more, see our tips on writing great answers.

draft saved

draft discarded

Post as a guest

Name

Required, but never shown

Name

Required, but never shown

Name

Required, but never shown

This page is only for reference, If you need detailed information, please check here

搜尋此網誌

Myujth