On 18/10/2013 16:04, Winnebeck, Jason wrote:
-----Original Message-----
From: Francesco Chicchiriccò [mailto:[email protected]]
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/
