Self documenting REST interface

Question

I have a Rails based server running several REST services and a Rails based web UI that interacts with the server using ActiveResource. Same server is being used by other clients( e.g: mobile). I have to generate documentation for the REST interface. I need to provide service URL, input/output and error document structure for each service.

Ideally, I would like to use an interceptor at the server side that will document the service based on the existing traffic. I am wondering if there is a gem to do this.

Answer 1

Darrel and Jon are correct, I would further add that your API should be discoverable at it's root. Read and write actions should be presented.

Check out Jon Moore's talk for further discussion at http://vimeo.com/20781278

Answer 2

When you are applying the REST architectural style, you do not need to document your interface.

The contract between client and server is established by the media type used, if you need any other additional documentation, you are not being RESTful.

So, instead of worrying about documenting your service, put all your descriptive effort into the documentation of your media types. Knowledge about media types is all that is necessary to implement the clients for your server.