REST API Doc article

I think the big problem with API docs is what to document. And it usually ends up with a comment per method, where you have “createFoo = creates a foo; deleteFoo = deletes a foo” and no real content. The question always becomes “well, what else?” And the real value of API docs is everything in between, the things you can’t infer by just looking at method signatures.

The following article is a good list of the other things you need to cover. It talks specifically about REST, but holds true for other API types, also. The TL;DR: what does a consumer need to know to actually use this API? How do you do auth? What are the business uses? What standards does it really follow? What are the other gotchas? What are the SLAs or other requirements for the service?

https://dzone.com/articles/rest-api-documentation-part-1