This week's giveaway is in the Java/Jakarta EE forum.
We're giving away four copies of Java EE 8 High Performance and have Romain Manni-Bucau on-line!
See welcome thread
Win a copy of Java EE 8 High Performance this week in the Java/Jakarta EE forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic

How do you like REST API documentation to look?  RSS feed

Posts: 16
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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?
today's feeble attempt to support the empire
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!