On 15/10/2013 17:10, Sergey Beryozkin wrote:
Hi
On 15/10/13 15:13, Winnebeck, Jason wrote:
I am using a tool called Enunciate to do this:
http://enunciate.codehaus.org/index.html
It's confusing at first because Enunciate generates interface
definition documents (like WADL) but also wants to publish your code,
it wants to replace the whole J2EE build environment. But you can use
it to generate documentation only, and I do that with its Maven
plugin. Then the generated WSDL, WADL, and XSD I feed into CXF as
pre-generated files, as if I was doing contract-first, even though I
am doing code-first. CXF is smart and replaces the endpoint URLs.
Interesting, Enunciate can be so useful.
It seems promising, but I'm not sure I want to give up with some
auto-generation goodies...
Francesco, I agree by the way that CXF @Description will typically
duplicate what JavaDocs can do for describing a given resource method,
I thought though that sometimes JavaDocs may be low-level a bit, if
you know what I mean, they won't necessarily match what is supposed to
go to the external world to see :-).
Agree: why not setting Javadoc elements as default values for their
@Description counterparts, when not provided?
As a side note @Description can also be quite fine-grained in
'targeting' specific WADL sections, given that pretty much every WADL
element has an optional doc element
Thanks, Sergey
Jason
-----Original Message-----
From: Francesco Chicchiriccò [mailto:[email protected]]
Sent: Tuesday, October 15, 2013 8:54 AM
To: [email protected]
Subject: WADL documentation via Javadoc?
Hi all,
by reading [1], I am currently annotating JAX-RS methods (for
WADL-generation) like this
/**
* Deletes the user matching the provided userId.
*
* @param userId id of user to be deleted
* @return Deleted user
*/
@DELETE
@Path("{userId}")
@Descriptions({
@Description(target = DocTarget.METHOD, value = "Deletes
the user matching the provided userId"),
@Description(target = DocTarget.RETURN, value = "Deleted
user")
})
UserTO delete(@PathParam("userId") Long userId);
As you can see, there is an evident duplication here, so I was thinking
if Javadoc elements might be used for WADL documentation and found [2]
for Jersey.
Is there anything similar planned for CXF?
TIA
Regards.
[1]
http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL
[2]
https://wikis.oracle.com/display/Jersey/SupportedJavadocTagsForExtendedWADL
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
