What most API documentation lacks is one thing.

Examples.

Real, working, copy-n-paste examples.

While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation.

Sure, schema helps, but having a spot to just lay out an example request or response is really important.

Another thing: often, one must perform prerequisite steps before making a call to a given API method. Eg - you must have booked a flight before checking in. The context surrounding how an API fits into its use-cases is as important as the API itself.