Support REST API doc generation

Issue by 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