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 >
