swagger (http://developers.helloreverb.com/swagger/) has been doing whats proposed here. By describing your APIs with swagger-spec you get a beautifully documented APIs, code generation of client libraries and some more stuff: https://github.com/wordnik/swagger-core/wiki/Downloads