There are several tools available that help documenting REST APIs. One of them is Swagger, an open source project under the Apache 2 license.
“The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.”
For REST APIs implemented in Java you can use Java annotations to document the REST APIs directly in the source code so that documentation and actual APIs are not out of synch. As part of this documentation you can not only define what parameters, types, etc. a service has but also which parameters are mandatory, validations, and more.
In order to create the actual documentation different mechanisms are available. For example you can use a Maven plugin to generate HTML files using markdown templates. Additionally there is a servlet that parses the documentation from the source code and serves it up as REST/JSON. This REST/JSON can then be consumed by custom user interfaces or via the out of the box Swagger UI.
Check out the samples developer.wordnik.com and petstore.swagger.wordnik.com. Similarly to the Social Business Toolkit API Explorer you can not only read the documentation, but also try the REST calls directly.
Last week the involved companies Reverb and Apigee announced the formation of a new working group which will work on the next version 2.0. Read the details.