I ended up having (mostly) the same needs. Thanks for posting this
question, I ended up going down the list and either researching each
module, or trying them out - and I'm *really* digging swagger. It's able to
piggy-back off what you already have, sort of a Decorator pattern, pretty
effectively. Before settling on swagger I was really liking IODocs, but the
problem is it has more dependencies than the others. In particular, you
have to have Redis running; so for our, app, this would mean running
another heroku instance just for hosting the API docs. Felt pretty overkill
- could have been worth it, but I think there were better alternatives.
On Wednesday, 31 July 2013 00:26:39 UTC-6, JVA wrote:
>
> Thank you for great answers! It is true that RESTful app should be
> self-documented. Anyway, if new user (human), which probably are new
> customer wan't create own client application, (s)he definitely needs some
> textual documentation about server-application, even if (s)he understand
> REST API model. For example documentation for each resources, why are they
> there and what purpose... My purpose now is to satisfy this section. But,,
> Maybe I didn't understand fully REST deeper purpose. I think most of
> ("hobby-users") didn't, because I tried to find pure RESTful style
> expressjs application, and I didn't found any! At least in my eyes those
> didn't look pure RESTful.. If you know some simple example but pure
> RESTful, please let me know.
> And I still believe that express routes can be used for documentation
> source, but definitely routes needs more associated meta information and I
> wonder how it would be best implement..At least routes contains all
> possible URL paths :) .
>
> Cheers,
> Jussi
>
> sunnuntai, 28. heinäkuuta 2013 17.17.12 UTC+3 Kevin Swiber kirjoitti:
>>
>> This sort of discussion ("What is REST?") might be better on the API
>> Craft Google Group. See:
>> https://groups.google.com/forum/#!forum/api-craft
>>
>> That's where my REST cronies and I hang out. It's very welcoming.
>>
>> I work in the REST API space and have been using Node almost exclusively
>> for Web APIs.
>>
>> In regards to HATEOAS: Hypermedia has not hit the mainstream. Hypermedia
>> nerds, such as myself, have not provided a great documentation story.
>> We're working on it. If you still need to build clients, you still need
>> documentation. Media type documentation often does not get into the
>> application semantics.
>>
>> For the mainstream acceptance of the meaning of REST, there's WADL for
>> describing APIs (
>> http://en.wikipedia.org/wiki/Web_Application_Description_Language).
>>
>> You can use something like WADL stylesheets to generate HTML
>> documentation (https://github.com/mnot/wadl_stylesheets/).
>>
>> The issue with generating docs from Express routes is that there's just
>> not enough meta information associated with a route. In theory, it might
>> not take much to generate docs out of comments associated with routes (a la
>> JSDoc). That might be something worth exploring.
>>
>> Cheers,
>>
>>
>> --
>> Kevin Swiber
>> Projects: https://github.com/kevinswiber
>> Twitter: @kevinswiber
>>
>>
>> On Sun, Jul 28, 2013 at 12:01 AM, Austin William Wright <
>> [email protected]> wrote:
>>
>>> 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 [email protected]
>>> To unsubscribe from this group, send email to
>>> [email protected]
>>> 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 [email protected].
>>> For more options, visit https://groups.google.com/groups/opt_out.
>>>
>>>
>>>
>>
>>
>>
--
--
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 [email protected]
To unsubscribe from this group, send email to
[email protected]
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 [email protected].
For more options, visit https://groups.google.com/groups/opt_out.
