Try to use the apiary.io idea. ^ ^
Em 02/01/2014 00:46, "Tyler Renelle" <[email protected]> escreveu:
> 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.
>
--
--
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.
