I guess I'll take this opportunity to plug my own little tool for this.
I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3].
But rather than relying upon source code annotations to have swagger auto-generate the documentation, or hand-writing swagger's verbose JSON structure, I created a little DSL for it as demonstrated at [4] and available on GitHub at [5].
Let me know if you have any questions about swagger-dsl. It's under-documented right now but perfectly functional. I use it often.
We've been working on updating our API to V2[1], and decided to go with grape because it automatically generates documentation via grape-swagger[2].
Initially we considered Apiary, but we wanted more flexibility and preferred to host things ourselves. And the fact that our documentation is generated automatically from the code via grape-swagger is a game changer.
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.
We love Swagger. It allows us to have uniform documentation across all our APIs regardless of dev writing style. It's a simple plan we can all stick to. Plus it gives you real API access inside the docs themselves. We highly recommend it and may I use this opportunity to thank the developer!
I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3].
But rather than relying upon source code annotations to have swagger auto-generate the documentation, or hand-writing swagger's verbose JSON structure, I created a little DSL for it as demonstrated at [4] and available on GitHub at [5].
Let me know if you have any questions about swagger-dsl. It's under-documented right now but perfectly functional. I use it often.
[1] http://swagger.io/
[2] https://github.com/swagger-api/swagger-ui
[3] http://petstore.swagger.wordnik.com/#!/pet
[4] http://intellinote.github.io/swagger-dsl/demo/live.html
[5] https://github.com/intellinote/swagger-dsl