Hacker News Reader

Comment by rodw | Hacker News Reader

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

View on HN

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.

[1] https://bikeindex.org/documentation/api_v2

[2] https://github.com/tim-vandecasteele/grape-swagger

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...

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.

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!

We use Swagger at work. Thanks for this!

We've (Workday) started using this internally and love it. Thankyou!

This is really cool. Thanks for sharing that!

Reply on news.ycombinator.com