Using Spring MVC is very straight forward for creating RESTful web services, I'm just struggling on a good way to generate documentation on how to consume those web services, and well as textual descriptions of what they do.

I've been browsing the internet, and have come across Swagger, which seems very consumer friendly when exploring a REST api. I see that someone has created a pretty nice implementation of this for Spring MVC, but I actually haven't tried it out myself yet.

What are others using to accomplish consumer friendly documentation? Are you keeping your documentation close to your code?

Thanks,

http://swagger.wordnik.com/
https://github.com/martypitt/swagger-springmvc