Big thanks to Henry Ho for asking about this during my REST presentation earlier this week. Apparently, it is common for REST services to notice an OPTIONS request (by that I mean a request made with the HTTP verb OPTIONS) and return an XML-descriptor of the service. I don't believe our docs cover this, but the feature works quite well actually. Here's a few examples.
Let's start with a very simple REST service:
To get the descriptor, I wrote a quick test script:
How about a more complex service? This one demonstrates dynamic resources.
In the result, which I've cropped a bit due to the size, you can see that the dynamic nature of the sub resources are documented well.
And finally - here's an example of how "produces" is represented. Here's a snapshot of a larger REST service. This method is used to return an image of a product.
And here is how it is returned: