News for hackers. Stuff that matters.
Re:Ask HN: What's the best way to write an API spec? by matt_kantor on Monday January 19, 2015 @02:37PM (#8913610)
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.

[1]: https://github.com/swagger-api/swagger-codegen/wiki/Creating...

Re:Ask HN: What's the best way to write an API spec? by rodw on Monday January 19, 2015 @06:14PM (#8914691)
Thanks Matt.

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.