I don't think this should really be necessary: The whole point of REST is that it's self-documenting, that any old user agent (like a web browser, but also robots) should be able to pull up the endpoint and start interacting with it.. This is typically done with HTML forms and hyperlinks (and actually, hyperlinks are mandantory -- that's what the HATEOAS component of REST is all about: Hypermedia as the Engine of Application State).
Some common problems are nicely detailed at < http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven>: There's two important points here, which I'll quote: - A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). *[Failure here implies that out-of-band information is driving interaction instead of hypertext.]* - A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. *[Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling]*. The gist here is that you shouldn't have to document how to use the service, beyond knowing consumption of the media types that are returned. If clients need to know out-of-bound information like how to form a URI (instead of following a server-provided hyperlink or form), then what you're creating isn't RESTful. For more machine-friendly endpoints, you can use Content-Type negotiation, JSON Hyper-Schema, and the "profile" and "describedby" link relations. On Wednesday, July 24, 2013 12:23:47 AM UTC-7, JVA wrote: > > Hi all, > > I'm wondering if anyone has tried to generate REST api documentation > (html) based directly to express routes ? > I would be also very interested to hear any comments related how to create > nice & entire REST api documentation. > I've tried find perfect solution but didn't find yet. > > My *requirements*: > -MD support > -html UI > -entire api doc, (all expressjs routes ) > -mongoose schema documentation support directly from schema > -(nice to have) possible to generate single file doc (e.g. pdf/doc/html) > > What I'm tried already (bold words is most critical thing why I didn't > select that library) : > > *apidoc* <https://npmjs.org/package/apidoc> > + MD support > + nice UI > + several comment tag supports > + pluggable > + generate html -> "offline usage" > + versioning > -* no TAC* (table of content) > *this might be possible to do with pluggin? > - needs a lot of comment tags to get good enought doc > - depends on comments how perfect document are > - If mongoose is used in back-end there is no easy way for *document > schemas *(related to REST-api) > *this can be done with pluggin. > > *express-api-docs* <https://npmjs.org/package/express-api-docs> > +routes based > *-no REST style* > * > * > Is there any other libraries ? Currently this apidoc seems to be best > solution for me, > but needs "a lot of" job to get all requirements fulfilled, but there > might be also several limitations... > > Best Regards, > Jussi > -- -- Job Board: http://jobs.nodejs.org/ Posting guidelines: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines You received this message because you are subscribed to the Google Groups "nodejs" group. To post to this group, send email to nodejs@googlegroups.com To unsubscribe from this group, send email to nodejs+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/nodejs?hl=en?hl=en --- You received this message because you are subscribed to the Google Groups "nodejs" group. To unsubscribe from this group and stop receiving emails from it, send an email to nodejs+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
