3scale (http://www.3scale.net) uses Swagger to do this out of the box on all of it's API portals. Swagger (see http://swagger.wordnik.com) gives you live docs but also tools to mark up the code to rip out the specs when you update code.