What is the best tool for documenting/generate reference for a RESTful/HTTP RPC API? [closed]

Question

Many questions have been posted and answered about REST / HTTP based APIs, etc, but none seem to have much information on the following question:

What tools are available/used to document a HTTP-RPC API? Which tools are the best?

A Similar question (specific to ASP.NET) from Jan 2009 can be found here, but with no answers.

I am in the process of developing several APIs both professionally and for personal projects (.NET MVC/OpenRasta, PHP, Coldfusion, etc..), and I haven't found anything in particular to help document these APIs. I am not looking for auto-generation based on code-parsing/scrubbing or anything like that. As you probably already know a RESTful/HTTP-based API should be client and platform agnostic; as such I would expect any documentation tool to be the same.

---

Features that a decent tool might have:

• Specify URLs/URIs format/structure
• Request/Response formats and methods (GET/POST/etc, XML/JSON/etc)
• Categorize endpoints/API Calls (such as grouping several calls under Authentication)
• Auto-generate static reference files/documentation like the examples below
• Include examples, test-cases, etc

---

Here are some examples of what I consider decent API documentation/reference(s) look like:

http://dev.twitter.com/doc/post/statuses/destroy/:id

http://www.salesforce.com/us/developer/docs/api_rest/index.htm

http://www.flickr.com/services/api/

Answer 1

SWAGGER is probably worth a look for you need. I use it for documenting REST entrypoints exposed by a java application using Jersey, but it looks like you can use it with other languages too.