search

ScaCap / spring-auto-restdocs

Spring Auto REST Docs is an extension to Spring REST Docs
https://scacap.github.io/spring-auto-restdocs/
Apache License 2.0
311 stars 86 forks source link

Does it make sense to extract the Javadoc extracting Doclet into a separate project? #435

Closed odrotbohm closed 10 months ago

odrotbohm commented 3 years ago

There are quite a few other projects that would benefit from having the Javadoc information for classes and methods available at build time for inclusion in some Asciidoctor files. I.e. it would be cool if there was a Doclet usable standalone (the current one apparently actually is but it might feel weird to refer to a Doclet specific to REST and RESTDocs in particular for general purposes) and an API to access the extracted content ideally already applying Asciidoctor specific transformations. For the latter, I think most of what's needed is already available in capital.scalable.restdocs.javadoc.

jmisur commented 3 years ago

Hi Oliver, that is an interesting idea. I don't know about any other project now which could use this, but I can imagine there is a potential. This would however require some additional work in order to make the json data structure or some kind of API more solid/flexible. So an example would help here.

odrotbohm commented 3 years ago

For Moduliths, we produce Asciidoctor snippets to document interesting parts of Spring applications. See this ticket for details. The corresponding commit introduces an abstraction to obtain documentation for a method and a Spring Auto RESTDocs based implementation that uses the metadata generated by the doclet.

The weird thing about the arrangement is that I now have to include a dependency that deals with REST API documentation on a project that potentially doesn't even expose an API just to be able to generate documentation for Spring internal event listeners. While inconvenient, it's also not a big problem for now. #434 slightly plays into this as well as the methods to be documented often use the same name and only differ in the method parameter.