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.
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 :-).
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
