How to build good documentation with REST API in Rails?
Tagged:
Currently, I am working on building RESTful web service in Rails. I am looking for some ways to build a good documentation in my Rails RESTful web service. I found some ways to do it:
- Wiki like Twitter API
- RDoc
- WADL (I'm not sure if anyone is currently using it?)
Could anyone gives any recommendations?
Are you saying you don't like the default output of these options?
If so, take a look at hanna or sdoc which will 'beautify' your rdoc. Cheers.
Answer 2
Scores:-3
If you mean that you want documentation to be generated for every URI that your routes have made available, then you are not following the constraints of REST. A RESTful API can only have your entry-point URI. Descriptions of your media types show how to discover other resources via URIs embedded in the hypertext of your responses. So, there's no automated way to do this.
See Sun Cloud API for a great example.
I found a good description on wikipedia with a few reference links, but there may be better ones, please help me to find these!
To be clear, I am not looking for implementation for any language specific implementation guides, just the pure concept.
...
How to automatically generate API documentation for Rails REST controller?
Is there any example I can look into using RDoc to do this?
...
I'm in the middle of writing a build and deployment document for a major enterprise platform, and I would appreciate a good example to use as a template for how to structure the document. Can anyone point me towards a good example of a well written build document? ...
I have some integration tests that get kicked off by TeamCity on a successful build. I have had success using the TeamCity REST API in order to tag the build as passed or failed, but would actually like to mark the build status as passed or failed (in the same ...
Where can I find useful documentation about using Shibboleth and SAML for SSO besides the Shibboleth Wiki pages, preferably for Ruby applications? Ruby-specific documentation for Shibboleth seems to be very sparse. Does anyone know good resources, tutorials or HowTos?
...
I am using Ruby on Rails 3.0.7 and I would like to document my application. To do that I would to find some "good" documentation about RDoc.
Where I can find that? That is, what are "the best" web resource where to find documentation about RDoc?
...
I am currently developing some plugins for Redmine, and I must say, I'm a bit disappointed with the lack of documentation available on this subject.
Normally, If I am looking for explanations on classes/methods, I need to spend a consistent amount of time browsing trough the core classes, and striving ...
So I'm building an application in Rails 3 using Devise as my authentication mechanism. I have all my controllers and views working. Our web site is humming along. Now we'd like to export our routes to 3rd party developers. The problem is how.
Here's the list of ...
I am using Ruby on Rails 3.1 and I would like to have an ordered list for my objects related to an has_many \ belongs_to association. To do that I am planning to use the acts_as_list gem (BTW: is it a good gem to make what I would ...
My api read data from a mongodb database and show it via a json api (so not much computational elaboration)
Can i see some performance report of both?
...
