Hi Francesco
On 22/10/13 14:58, Francesco Chicchiriccò wrote:
On 21/10/2013 11:31, Sergey Beryozkin wrote:
Hi Francesco,
On 21/10/13 07:58, Francesco Chicchiriccò wrote:
On 18/10/2013 19:06, Sergey Beryozkin wrote:
Hi All,
I wonder if we can try and add a property to WadlGenerator, such as
"checkJavaDocs" or may be "javaDocsClassPath" which will point to a
generated java docs jar, then suppose it processes a root class like
mypackage.Root, then it will look for /mypackage/Root.html Java Doc
resource, load it and try to scrape HTML (it seemed to be a proper
XML) for the info. I've no idea if it will work but I might give it
a try;
+1
This would be a very nice add-on, IMHO.
I'm just hoping it may be the simplest way to do it because the
generator has all the context info in time it may decide to check for
a javadocs resource, ex, it will know that the current root resource
or even subresource method is a JAX-RS method after all, that no
@Description targeting specific method or parameters exist, so it
might be simpler;
The possible downside is that if it works then a generated JavaDocs
jar would need to be shipped;
I also like the idea of auto-generating Descriptions with ASM, I'd
try to explore it further if the above will prove to be too messy
and unrealistic...
+1
Also this seems to be a nice option, actually even lighter for
end-users, I'd say.
Yes, no need to ship a javadocs jar and do any extra config, but I
agree with Dan, it is a bit more involved to implement :-), we'll see,
may be we'll end up supporting multiple options here.
Is there any issue open for this work? I'd like to link it to
SYNCOPE-151 and possibly wait for its resolution before proceeding
further with my current work of cloning Javadocs to @Description.
Sure, please link to
https://issues.apache.org/jira/browse/CXF-5353
Anyway, I've come to something usable about transforming WADL to HTML;
you can browse a demo of Apache Syncope 1.2.0-SNAPSHOT API at
http://people.apache.org/~ilgrosso/wadl2html/
That is actually quite cool, given it is actually a start, really nice
Consider that only /users has been documented via @Description so far.
Basically, a couple of XSL stylesheets (one for schema, one for
resources) take the application.wadl generated by CXF as input and
generates some HTML pages, with some jQuery spice.
The demo above was statically generated from a Cocoon 3 web application;
the project is hosted at
https://github.com/Tirasa/wadl2html
I've started with a pure Cocoon 3 webapp because it was faster for me to
proceed this way, but I'll make soon a servlet doing the same job - and
I'll add that to Syncope, for live WADL rich browsing.
Cocoon had to be tried first, yes :-)
FYI, CXF ships XSLTJaxbProvider which can be configured say with a
custom (master stylesheet) and process for example a DOM Document,
however right now it won;t work with WADLGenerator as it only produces
Document if JSON is expected (with JSONProvider copying it to Jettison
via CXF STAX handler).
I'll have a look on how to make both providers working together
Thanks, Sergey
Regards.
Thanks for taking this seriously ;-)
Np, thanks for initiating this thread, I can't prioritize immediately
on this issue but hope we can make it work somehow soon enough...
Cheers, Sergey
Regards.
On 18/10/13 09:59, Francesco Chicchiriccò wrote:
On 15/10/2013 17:32, Daniel Kulp wrote:
Interesting…. We haven't really looked at anything javadoc related as
that information isn't available at runtime. It's only available at
build time and thus we'd need special tools and such to parse the
javadoc at build time, output a file or something that can be picked
up later.
Jersey has a javadoc doclet that will output a special XML file that
the runtime can be configured to augment the stuff that the runtime
produces. We could likely use the exact same XML file so we don't
need to produce our own doclet. That said, that does require that
the maven javadoc plugin be configured to ALWAYS run as part of your
build. That does slow the builds down a little bit.
Another option COULD be a "doclet" that would use ASM or something to
actually update the compiled .class files with @Description
annotations. Definitely more involved and likely wouldn't work as
well in an IDE though.
I've been trying Enunciate in these days, for documentation only [3],
via its maven plugin.
While generating <doc> elements from Javadocs was working fine (I
guess
with an approach similar to what reported above), I have found some
other serious issues: no support for base types (xs:int, xs:string,
...
are just ignored), no support for JAXB collections [4], ...
I gave up with Enunciate then - even though their HTML output looks
quite nice - and came back to "pure" CXF WADL generation: I am now
working on something to generate some HTML from WADL via XSLT.
Regards.
On Oct 15, 2013, at 8:53 AM, Francesco Chicchiriccò
<ilgro...@apache.org> wrote:
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
[3] http://docs.codehaus.org/display/ENUNCIATE/Documentation+Only
