Hi Francesco
On 14/10/13 10:54, Francesco Chicchiriccò wrote:
Hi all,
quite a long while ago we discussed about the best way to make RESTful
services self-documenting and created SYNCOPE-151; as you can read
there, however, everygthing was particularly meant for Spring MVC (CXF
came afterwards).
I'd like to update SYNCOPE-151 (with CXF) and bring it to 1.2.0.
Talking about the way how to implement such feature, I first went to
Swagger [1] and took a deep lok to their CXF example [2]: it works but I
found it quite heavy (~40 MB of WAR file for a very basic sample
service), guess mainly due to Scala compiler.
From the other side, one can think to enrich the auto-generated WADL
[3] and to beautify the HTML output via XSLT (I've found several
examples we can start from, like as [4]).
As old cocooner, my preference is by far for the latter: WDYT?
The 2nd option should work well, note it is also possible to create a
WADL document manually and link to the endpoint as (CXF)
jaxrs:server/@docLocation attribute.
I like this style:
https://dev.twitter.com/docs/api/1.1
it appears WADL can be easily enough processed by XSLT to offer
something similar, though I think CXF would need to be enhanced a bit to
support the user browsing through the individual links, which should not
be a problem
Cheers, Sergey
Regards.
[1] http://swagger.wordnik.com/
[2]
https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs-cxf
[3]
http://cxf.apache.org/docs/jaxrs-services-description.html#JAXRSServicesDescription-WADLAutoGeneration
[4] https://github.com/ipcsystems/wadl-stylesheet
