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.<p>I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3].<p>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].<p>Let me know if you have any questions about swagger-dsl. It's under-documented right now but perfectly functional. I use it often.<p>[1] <a href="http://swagger.io/" rel="nofollow">http://swagger.io/</a><p>[2] <a href="https://github.com/swagger-api/swagger-ui" rel="nofollow">https://github.com/swagger-api/swagger-ui</a><p>[3] <a href="http://petstore.swagger.wordnik.com/#!/pet" rel="nofollow">http://petstore.swagger.wordnik.com/#!/pet</a><p>[4] <a href="http://intellinote.github.io/swagger-dsl/demo/live.html" rel="nofollow">http://intellinote.github.io/swagger-dsl/demo/live.html</a><p>[5] <a href="https://github.com/intellinote/swagger-dsl" rel="nofollow">https://github.com/intellinote/swagger-dsl</a>