1. jaxrs-spec@javaee.groups.io

Re: doc property for all JAX-RS annotations

Pavel Bucek
 

Hi Sergey,

I believe that javadoc is the right place for documentation like this. Not to mention that writing the documentation to the annotation string literal is not very convenient, especially when the text would span multiple lines.

I think I get what usecase addressed here, but seems like the proposed solution would not provide solution of related issues. It would reduce "documentation" annotations, but various doc tools would still require additional annotations.

Thanks and regards,
Pavel

On 13/06/2017 14:17, Sergey Beryozkin wrote:
Hi

I created an issue awhile back to get something like

@Path(value="/", doc="the path")

supported for all of the JAX-RS annotations.

The idea is to come up with a single well known property that the future code or service api info generation tools can use.

For example, some use JavaDocs - which overloads it a bit because what is documented at the Java level and what is visible to the HTTP service consumer may not always make sense to keep in sync.
Then we have Swagger2 annotations related to the docs, in CXF we also have @Description annotations that can be used by the WADL filter.

Having a 'doc' would be a simple improvement which can help to minimize the 'noise' related to everyone using their own annotations/approaches to documenting JAX-RS API...

Sergey
Join jaxrs-spec@javaee.groups.io to automatically receive all group messages.