[DISCUSS] Document RESTful APIs

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[DISCUSS] Document RESTful APIs

ilgrosso
Administrator
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?

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

--
Francesco Chicchiriccò

ASF Member, Apache Syncope PMC chair, Apache Cocoon PMC Member
http://people.apache.org/~ilgrosso/

Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Document RESTful APIs

Fabio Martelli
Il 14/10/2013 11:54, Francesco Chicchiriccò ha scritto:

> 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?
I agree with you, Francesco.
 From my PPOV, Swagger/Scala discarding is wise.

Regards,
F.
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Document RESTful APIs

Sergey Beryozkin
In reply to this post by ilgrosso
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