11–20 of 58 posts
There have been an explosion of API specification formats in the last few years. No clear winner has emerged. JSON Schema and JSON Hyperschema are JSON-based formats for describing JSON and REST (hypermedia-driven) APIs. The formats make decent sense and can be used to generate docs, validators, client libraries, UIs, and more. http://json-schema.org/ API Blueprint is another emerging format for API description. It's…
And been working on a tool to merge the schema with actual code for Sinatra apps: https://github.com/pedro/sinatra-schema
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…
We tried a lot of options at Lavaboom (including apiary, readme.io, swagger, etc) and ended up using Slate: https://github.com/tripit/slate
Have a look at http://apiary.io and http://readme.io
The documentation they provide based on the specs looks very well designed and intuitive.
One of my favorite features about apiary was the mock backend server they use based on my API specs. So if you're doing a single page app, just write your specs then point your frontend app to the mock server they provide. This greatly simplified development process for me.
Once the format is nailed down it's easier to write documentation, and the server side code will go quickly because less time is spent iterating changes.
Does anyone know of any API specs written for websocket APIs?
I am working on creating a websocket API and would like to at least look at a few other examples.