How to build good documentation with REST API in Rails?

Question

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?

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.

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.