I liked swagger a lot, but could never get it working with my API because it's too opinionated. From the little I tried to do, there was no way at all to tell it to document the API the way I had designed it, rather than the way it thought APIs should be designed.
Reminds me of IO/Docs which I use actively for my own application. I like the ability to "try it yourself" though a mix of it with "here is the default response if it works, here is the response if it fails" is better for POST/PUT/DELETE routes.
Comments
Is is just me, or are their docs kind of yuck/hard to read?
http://docs.timdorr.apiary.io/#vehiclecommands
My biggest problem: way too much visual emphasis on 'GET' part and not enough on the actual URL. That has way more priority, to me.
I like the swagger layout. http://swagger.wordnik.com/#!/pet
Their developer documentation is kind of tricky to figure out though.
I liked swagger a lot, but could never get it working with my API because it's too opinionated. From the little I tried to do, there was no way at all to tell it to document the API the way I had designed it, rather than the way it thought APIs should be designed.
Nice layout.
Reminds me of IO/Docs which I use actively for my own application. I like the ability to "try it yourself" though a mix of it with "here is the default response if it works, here is the response if it fails" is better for POST/PUT/DELETE routes.
I actually agree and find them very unappealing. They seem too dense and the text either too light, too small, or both.
I think they look great. I could imagine having a few nitpicks, but never describing them as "yuck"