BTW, Swagger-codegen has [support for writing specs in YAML][1] too, if that's your thing.
My team makes uses generated Swagger API docs (via the swagger-play2 plugin), but to be honest the tooling around it is pretty half-assed. Having a machine-readable spec is a game changer, though.
I looked at swagger-codegen before createing swagger-dsl, and frankly it is pretty nice, but with respect to authoring the underlying Swagger specification document, swagger-codegen is just a direct YAML translation of the original Swagger JSON format.
In other words, swagger-codegen's YAML support is just a YAML-to-JSON transformation. It has the same redundancies and structural issues as Swagger's JSON, just in a YAML syntax.
My objective with swagger-dsl was to create a more human-oriented (more readable, less verbose, less error prone, more DRY, etc.) format for authoring those JSON documents for Swagger. It's not just JSON-as-YAML, it's a more author-oriented (as opposed to parser-oriented) way to describe the API.
My team makes uses generated Swagger API docs (via the swagger-play2 plugin), but to be honest the tooling around it is pretty half-assed. Having a machine-readable spec is a game changer, though.
[1]: https://github.com/swagger-api/swagger-codegen/wiki/Creating...