I’m tasked with designing a format for on-line documentation of several REST APIs. I’m supposed to use the “new style” format supported by documentation tools like Swagger, as opposed to something modeled after C library documentation or Javadoc. I'm told that this is the de facto standard for modern API documentation, and it is what developers who use REST APIs expect and like.
I've examined over a dozen REST API documentation sets published by leading web businesses like Twitter, Google, and LinkedIn. They don't seem to have anything in common that would help me define what the "new style" of API documentation is. Some of them do things I’d never do, such as providing examples of how to use the API but no formal description of the request and response elements. That undercuts whatever authority they have as examples of good practice.
I’m looking for some independent input here. What do you, as a consumer of REST API documentation, expect and want? What sites can you point to as models to emulate, and why?