so...yaml for the win? :))

So, we ended up by using https://rubygems.org/gems/oas_rails which does the heavy work and generates almost everything. We only had to document the endpoints.

Have you tried Tower?