5 ms·
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-base
by rodw 12y ago
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/ http://swagger.io/
[2] https://github.com/swagger-api/swagger-ui https://github.com/swagger-api/swagger-ui
[3] http://petstore.swagger.wordnik.com/#!/pet http://petstore.swagger.wordnik.com/#!/pet
[4] http://intellinote.github.io/swagger-dsl/demo/live.html http://intellinote.github.io/swagger-dsl/demo/live.html
[5] https://github.com/intellinote/swagger-dsl https://github.com/intellinote/swagger-dsl
- philjr 12y agoWe've (Workday) started using this internally and love it. Thankyou!
- tomashertus 12y agoThis is really cool. Thanks for sharing that!
- matt_kantor 12y agoBTW, 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-Swagger-JSON-from-YAML-files https://github.com/swagger-api/swagger-codegen/wiki/Creating...
- rodw 12y agoThanks 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.
- marquis 12y agoWe 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!
- bike_index 12y agoWe'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 https://bikeindex.org/documentation/api_v2 [2] https://github.com/tim-vandecasteele/grape-swagger https://github.com/tim-vandecasteele/grape-swagger
- Chris911 12y agoWe use Swagger at work. Thanks for this!