I think this is a really good idea. So far I have been using Enunciate to do exactly this (http://www.sonatype.com/people/2010/02/documenting-the-nexus...). I have been happy with Enunciate so far but they seem to have lost traction and their API does not work with Java 7 for instance. Swagger looks a bit cooler too ;)

That being said, there are some thing that they do that Swagger seems to be missing (or I am just missing it). For instance Enunciate does not require any custom annotations but uses the normal Javadoc instead, which is a very good feature. And how do I run Swagger, can I plug this into my Maven build process and include in the generated war file?