Support REST API doc generation

**Issue by [guersam](https://github.com/guersam)**
_Saturday Dec 20, 2014 at 23:05 GMT_
_Originally opened as https://github.com/akka/akka/issues/16591_

---

Related ML thread: https://groups.google.com/forum/#!topic/akka-user/d18_smRGeoE

> Hi,
>
> Although this topic has been discussed several times in spray-user list [1], I'd like to refresh this issue because I think it's an important feature for wider adoption as well as the mostly asked ones like WebSocket.
>
> Spray/akka-http's routing DSL is the best among the existing framework/libraries IMO, however, it's cascaded and mixed routing structure makes automated documentation and code generation somewhat difficult. Although there's already good looking spray-swagger, it's annotation based approach seems too verbose sometimes.
>
> A random thoughts for alternatives are:
> 1. Macro based introspection which extracts routing structure from the DSL
> 2. Integration with the testkit (either way of doc <-> test code generation) instead of with routing code directly
>
> I know it isn't urgent now, just hoping to gather some wisdom to bring it to the next step for the long term goal.
>
> Regards,
> Jisoo
>
> [1] https://groups.google.com/forum/#!searchin/spray-user/swagger
> [2] https://github.com/gettyimages/spray-swagger
> [3] http://www.scalatra.org/2.3/guides/swagger.html

Start by reading the routing DSL discussion, the linked spray-swagger project, and the related Akka user mailing-list thread. The issue proposes macro-based routing introspection or testkit integration but names no files or tests; the work is done when a decided approach supports REST API documentation generation.

Written by the indexing model from the issue text.