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

Re:Ask HN: What's the best way to write an API spec? by bike_index on Monday January 19, 2015 @03:15PM (#8913806)
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

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.

Re:Ask HN: What's the best way to write an API spec? by marquis on Monday January 19, 2015 @02:59PM (#8913709)
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!
Re:Ask HN: What's the best way to write an API spec? by Chris911 on Monday January 19, 2015 @05:46PM (#8914600)
We use Swagger at work. Thanks for this!
Re:Ask HN: What's the best way to write an API spec? by philjr on Monday January 19, 2015 @01:21PM (#8913143)
We've (Workday) started using this internally and love it. Thankyou!
Re:Ask HN: What's the best way to write an API spec? by tomashertus on Monday January 19, 2015 @01:33PM (#8913210)
This is really cool. Thanks for sharing that!