Ask HN: What's the best way to write an API spec?
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.[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