Thanks for the info. Eric MacAdie
On Tue, Sep 14, 2010 at 3:45 PM, Sergey Beryozkin <[email protected]>wrote: > Hi > > On Tue, Sep 14, 2010 at 8:39 PM, Daniel Kulp <[email protected]> wrote: > > > On Monday 13 September 2010 2:16:21 pm Eric MacAdie wrote: > > > We are making a REST API at our company, and we need to provide > > > documentation. Are there any standards for documenting REST APIs? > > > > Well, for "standards" type things, there really is just WADL (supported > by > > CXF > > and Jersey and possibly others) and WSDL 2.0 (possibly just Axis2). For > > CXF > > and Jersey, if you have a JAX-RS service, the WADL things can be > generated > > automatically. > > > > > CXF supports @Description annotations which if present (on resource class > or > methods) will 'contribute' to the generated WADL instance. > > I've heard someone created JavaDocs extensions for documenting JAXRS > services. > > As far as WADL is concerned, it's not very easy to read for a human user, > though it is a simple language. It would be good to have a default > stylesheet (unless a user provides another one) which would produce a > simple > and informative HTML page. I was planning to do it few months ago - might > get to it later on > > > > > Can > > > anybody recommend some API docs to emulate or to avoid? What do people > > > think of the docs for some existing web services, like Yelp, Amazon, > > > LinkedIn, etc? > > > > > I just like simple tables showing URI, HTTP methods, possible media types, > this sort of information can be obtained from WADL with the help of > stylesheets > > cheers, Sergey > > Can't really help on that. Sorry. :-( > > > > Dan > > > > > > > > > > Thanks for any input. > > > > > > Regards, > > > Eric MacAdie > > > > -- > > Daniel Kulp > > [email protected] > > http://dankulp.com/blog > > >
