How to build good documentation with REST API in Rails?


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?

2009-08-18 02:26:15 Scores:4
Documentation in which way? Are you talking about documenting the code of your rails application?
2009-08-18 13:51:19 Scores:0
I'm talking about documenting api that lets outside others developers be able to build on top the api.
2009-08-24 11:31:09 Scores:0
Walking WikiH
2012-07-25 15:06:53 Scores:0

2 answers

Answer 1

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.

theIV H
2009-08-18 02:29:52
Answer 2

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.

aehlke H
2009-08-18 14:03:44
If you don't care about REST though, there are automated ways to generate docs for your URLs...
aehlke H
2011-01-08 00:47:55 Scores:0
Share |
View original post at

Related topics

Where can I find a good documentation about the core concept of REST?

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 auto generate Rails REST API documentation for controllers?

How to automatically generate API documentation for Rails REST controller? Is there any example I can look into using RDoc to do this? ...

Good Examples of Build and Deployment Documentation

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? ...

Fail build via REST API with TeamCity, from another build config, after build is already finished

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 ...

Good documentation about Shibboleth and SAML?

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? ...

Where to find good RDoc documentation?

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? ...

Good documentation for writing Redmine plugins

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 ...

How do I generate public documentation for my Rails 3 REST Service?

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 ...

Where can I find some good documentation about the 'acts_as_list' gem?

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 ...

Do you think it is a good choice using node.js instead of Ruby on Rails to build an API Web Service?

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? ...