Re: WADL documentation via Javadoc?
On 22/10/2013 17:05, Sergey Beryozkin wrote: 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 Waiting for this (any issue on JIRA?), I have developed a simple servlet [4] that makes easier to embed the WADL2HTML mechanism into existing CXF-based web applications. 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
Re: WADL documentation via Javadoc?
Hi, On 23/10/13 12:40, Francesco Chicchiriccò wrote: On 22/10/2013 17:05, Sergey Beryozkin wrote: 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 Waiting for this (any issue on JIRA?), I have developed a simple servlet [4] that makes easier to embed the WADL2HTML mechanism into existing CXF-based web applications. Yes, hoping https://issues.apache.org/jira/browse/CXF-5356 can help do it at the JAX-RS level only 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,
Re: WADL documentation via Javadoc?
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.
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/
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.
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
Re: WADL documentation via Javadoc?
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
Re: WADL documentation via Javadoc?
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 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.
Thanks for taking this seriously ;-)
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
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
Re: WADL documentation via Javadoc?
On 18/10/2013 17:08, Winnebeck, Jason wrote: -Original Message- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Friday, October 18, 2013 10:21 AM I could not get any XML type information about method parameters; WADL fragment was something like param name=executionId style=template/ while I would have expected (and which I actually get from CXF) param name=executionId style=template type=xs:long/ Thanks for sharing your story, so I can keep this in mind if I run into these issues myself. I didn't think about primitive returns. I didn't have any in my web service. When I read your first mail I got the impression you meant it didn't support primitives or collections anywhere in the data model, which sounded a little too wild. This is exactly what I did for a couple of days: playing with source code and fmt files, rebuilding Enunciate and checking in my project: too much long, error prone and ineffective. Yes, I also had to fight with it for a long time, ultimately I was successful except I found a bug where in WSDL (http://jira.codehaus.org/browse/ENUNCIATE-804) when it never can generate elementFormDefault=qualified, and I couldn't find a reason not to use unqualified in XSD so I ended up doing that as a workaround. So in the end I got lucky enough but if anything else came about I would probably have given up. So I think I will have some big reservations to suggest Enunciate in the future. My XSLT-based processing tool is instead progressing well: if you are interested I'll let you know when it's ready. I think this would be very useful for people who have gotten CXF to generate documentation through annotations, or contract-first development. Myself specifically I can't use it because my docs are in Javadoc so CXF-generated WADL would be missing all documentation. I also have the issue that my service is JAX-RS and WS at the same time. For example, Jersey for JAX-RS can do WADL from javadocs, but I chose CXF to do RS and WS at the same time. Have you looked at Swagger? I originally got into Enunciate because my initial approach was to create a Swagger file by hand, and on their site they have a link to Enunciate because it can generate the Swagger description file (in addition to everything else, plus taking its info from Javadocs). But maybe I took one step too far... Oh yes, I've tried Swagger (via their JAX-RS / CXF sample [1]) and I really like its output; however, the final WAR from such very basic sample is about 40 MB, mainly due to Scala compiler and other artifacts: definitely too loaded for my needs, so I gave up. Regards. [1] https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs-cxf -- Francesco Chicchiriccò ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member http://people.apache.org/~ilgrosso/
Re: WADL documentation via Javadoc?
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.
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
RE: WADL documentation via Javadoc?
-Original Message- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Monday, October 21, 2013 3:08 AM Oh yes, I've tried Swagger (via their JAX-RS / CXF sample [1]) and I really like its output; however, the final WAR from such very basic sample is about 40 MB, mainly due to Scala compiler and other artifacts: definitely too loaded for my needs, so I gave up. Regards. [1] https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs- cxf Yes, I had the same thought initially too, I didn't want all of those runtime dependencies. So I thought about compile-time generation. On their wiki[1] they list swagger-jaxrs-doclet[2] and Enunciate. I tried the doclet and found it was incomplete, and that's how I ended up going down the Enunciate path. Going back to a different wiki[3] I actually see a few more options I didn't notice before: SoapUI and swagger-maven-plugin[4]. [1] https://github.com/wordnik/swagger-core/wiki/Java-Integrations [2] https://github.com/ryankennedy/swagger-jaxrs-doclet [3] https://github.com/wordnik/swagger-core/wiki/No-server-Integrations [4] https://github.com/kongchen/swagger-maven-plugin Jason -- This email message and any attachments are for the sole use of the intended recipient(s). Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message and any attachments.
Re: WADL documentation via Javadoc?
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
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
Re: WADL documentation via Javadoc?
On 18/10/2013 10: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],
...
Oops, missing link :-S
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
[4] https://jira.codehaus.org/browse/ENUNCIATE-429
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
RE: WADL documentation via Javadoc?
-Original Message- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Friday, October 18, 2013 5:00 AM 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. Can you explain a little bit more about the issues you have? The documentation I'm getting looks reasonable, if something is a string it says it's a string, on both attributes and elements? It also is supporting collections inside types fine. But you linked to https://jira.codehaus.org/browse/ENUNCIATE-429 which is an issue with collections as returns from service interface. When I first tried JAX-RS I was doing that but I've never made it to a production service with that technique because I've always run into problems if you want to support XML, because there's no namespace/XSD/root element entry, and implementations like Jersey create adhoc elements that wouldn't be defined in XSD, meaning there's no schema validation. So I've always ended up having to make wrapper classes similar to what you see with SOAP so that the request/responses are always a concrete class (not an interface) with no generics. It appears issues with tools like Enunciate is another disadvantage of that technique. I certainly won't say that Enunciate isn't rock solid, I've encountered a bit of limitations/bugs I've had to work around but it's not /that/ broken. Another tip with Enunciate is all of the output is done through freemarker templates. So even if you want to consider XSLT approach, you could do something similar with Enunciate. I've been able to tweak the output via a custom template in the modules/docs configuration. From that template you can completely adjust the entire sites output except for the WSDL/WADL/XSD files themselves. Those are also done with freemarker but I don't see a way to customize them; you'd have to adjust and rebuild enunciate source to change those I think. Jason Winnebeck -- This email message and any attachments are for the sole use of the intended recipient(s). Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message and any attachments.
Re: WADL documentation via Javadoc?
On 18/10/2013 16:04, Winnebeck, Jason wrote: -Original Message- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Friday, October 18, 2013 5:00 AM 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. Can you explain a little bit more about the issues you have? The documentation I'm getting looks reasonable, if something is a string it says it's a string, on both attributes and elements? I could not get any XML type information about method parameters; WADL fragment was something like param name=executionId style=template/ while I would have expected (and which I actually get from CXF) param name=executionId style=template type=xs:long/ I was anyway able to get enunciate sources and extend some behavior in order to get trough this (very hardly actually) in the application.wadl. When it came to docs.xml (the one from which the HTML files are generated) however, the Framemarker variable I've added was inexplicably null: after a whole day lost behind this, I gave up. It also is supporting collections inside types fine. But you linked to https://jira.codehaus.org/browse/ENUNCIATE-429 which is an issue with collections as returns from service interface. When I first tried JAX-RS I was doing that but I've never made it to a production service with that technique because I've always run into problems if you want to support XML, because there's no namespace/XSD/root element entry, and implementations like Jersey create adhoc elements that wouldn't be defined in XSD, meaning there's no schema validation. So I've always ended up having to make wrapper classes similar to what you see with SOAP so that the request/responses are always a concrete class (not an interface) with no generics. It appears issues with tools like Enunciate is another disadvantage of that technique. We have been successfully using JAXB collections with CXF and I don't see enough reason to adjust our API for suiting a documentation tool, hence no choice. I certainly won't say that Enunciate isn't rock solid, I've encountered a bit of limitations/bugs I've had to work around but it's not /that/ broken. Another tip with Enunciate is all of the output is done through freemarker templates. So even if you want to consider XSLT approach, you could do something similar with Enunciate. I've been able to tweak the output via a custom template in the modules/docs configuration. From that template you can completely adjust the entire sites output except for the WSDL/WADL/XSD files themselves. Those are also done with freemarker but I don't see a way to customize them; you'd have to adjust and rebuild enunciate source to change those I think. This is exactly what I did for a couple of days: playing with source code and fmt files, rebuilding Enunciate and checking in my project: too much long, error prone and ineffective. My XSLT-based processing tool is instead progressing well: if you are interested I'll let you know when it's ready. Have a nice WE. Regards. -- Francesco Chicchiriccò ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member http://people.apache.org/~ilgrosso/
RE: WADL documentation via Javadoc?
-Original Message- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Friday, October 18, 2013 10:21 AM I could not get any XML type information about method parameters; WADL fragment was something like param name=executionId style=template/ while I would have expected (and which I actually get from CXF) param name=executionId style=template type=xs:long/ Thanks for sharing your story, so I can keep this in mind if I run into these issues myself. I didn't think about primitive returns. I didn't have any in my web service. When I read your first mail I got the impression you meant it didn't support primitives or collections anywhere in the data model, which sounded a little too wild. This is exactly what I did for a couple of days: playing with source code and fmt files, rebuilding Enunciate and checking in my project: too much long, error prone and ineffective. Yes, I also had to fight with it for a long time, ultimately I was successful except I found a bug where in WSDL (http://jira.codehaus.org/browse/ENUNCIATE-804) when it never can generate elementFormDefault=qualified, and I couldn't find a reason not to use unqualified in XSD so I ended up doing that as a workaround. So in the end I got lucky enough but if anything else came about I would probably have given up. So I think I will have some big reservations to suggest Enunciate in the future. My XSLT-based processing tool is instead progressing well: if you are interested I'll let you know when it's ready. I think this would be very useful for people who have gotten CXF to generate documentation through annotations, or contract-first development. Myself specifically I can't use it because my docs are in Javadoc so CXF-generated WADL would be missing all documentation. I also have the issue that my service is JAX-RS and WS at the same time. For example, Jersey for JAX-RS can do WADL from javadocs, but I chose CXF to do RS and WS at the same time. Have you looked at Swagger? I originally got into Enunciate because my initial approach was to create a Swagger file by hand, and on their site they have a link to Enunciate because it can generate the Swagger description file (in addition to everything else, plus taking its info from Javadocs). But maybe I took one step too far... Jason Winnebeck -- This email message and any attachments are for the sole use of the intended recipient(s). Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message and any attachments.
Re: WADL documentation via Javadoc?
Hi On 18/10/13 15:04, Winnebeck, Jason wrote: -Original Message- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Friday, October 18, 2013 5:00 AM 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. Can you explain a little bit more about the issues you have? The documentation I'm getting looks reasonable, if something is a string it says it's a string, on both attributes and elements? It also is supporting collections inside types fine. But you linked to https://jira.codehaus.org/browse/ENUNCIATE-429 which is an issue with collections as returns from service interface. When I first tried JAX-RS I was doing that but I've never made it to a production service with that technique because I've always run into problems if you want to support XML, because there's no namespace/XSD/root element entry, and implementations like Jersey create adhoc elements that wouldn't be defined in XSD, meaning there's no schema validation. So I've always ended up having to make wrapper classes similar to what you see with SOAP so that the request/responses are always a concrete class (not an interface) with no generics CXF will add schema xs:elements to the generated WADL grammar in case of the explicit collections to represent the wrappers it puts around them; same for @XmlType only beans (since yesterday) Cheers, Sergey . It appears issues with tools like Enunciate is another disadvantage of that technique. I certainly won't say that Enunciate isn't rock solid, I've encountered a bit of limitations/bugs I've had to work around but it's not /that/ broken. Another tip with Enunciate is all of the output is done through freemarker templates. So even if you want to consider XSLT approach, you could do something similar with Enunciate. I've been able to tweak the output via a custom template in the modules/docs configuration. From that template you can completely adjust the entire sites output except for the WSDL/WADL/XSD files themselves. Those are also done with freemarker but I don't see a way to customize them; you'd have to adjust and rebuild enunciate source to change those I think. Jason Winnebeck -- This email message and any attachments are for the sole use of the intended recipient(s). Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message and any attachments.
Re: WADL documentation via Javadoc?
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;
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...
Thanks, Sergey
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
--
Sergey Beryozkin
Talend Community Coders
http://coders.talend.com/
Blog: http://sberyozkin.blogspot.com
RE: WADL documentation via Javadoc?
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.
Jason
-Original Message-
From: Francesco Chicchiriccò [mailto:ilgro...@apache.org]
Sent: Tuesday, October 15, 2013 8:54 AM
To: users@cxf.apache.org
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/
--
This email message and any attachments are for the sole use of the intended
recipient(s). Any unauthorized review, use, disclosure or distribution is
prohibited. If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message and any attachments.
Re: WADL documentation via Javadoc?
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:ilgro...@apache.org]
Sent: Tuesday, October 15, 2013 8:54 AM
To: users@cxf.apache.org
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
Re: WADL documentation via Javadoc?
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:ilgro...@apache.org]
Sent: Tuesday, October 15, 2013 8:54 AM
To: users@cxf.apache.org
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/
Re: WADL documentation via Javadoc?
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.
Dan
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
--
Francesco Chicchiriccò
ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/
--
Daniel Kulp
dk...@apache.org - http://dankulp.com/blog
Talend Community Coder - http://coders.talend.com
