Comment by craigsmitham

This looks promising. I think there is value from separating the spec from the implementation details. Here is a dream workflow:

* version controlled canonical specs and documentation of API using apistudio.io

* use existing Swagger extensions to build out Swagger spec from implementation

* Some tool to automatically compare/verify canonical swagger spec with spec generated by framework plugin