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

api rest documentation-generation
Colin picture Colin · Jun 6, 2011 · Viewed 7.6k times · Source

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

Michael Zilbermann picture Michael Zilbermann · Feb 11, 2013

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.

Related questions

Creating html doc from postman collection

I've developed a pretty extense API, and I have it on Postman, which works pretty nice. Now I have to generate an html doc to keep it versioned inside /docs along with my sources. Is there a tool or a …

Read More
How do I make calls to a REST API using C#?

This is the code I have so far: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System; using System.Net.Http; using System.Web; using System.Net; using System.IO; namespace ConsoleProgram { public class Class1 { …

Read More
How do you set the Content-Type header for an HttpClient request?

I'm trying to set the Content-Type header of an HttpClient object as required by an API I am calling. I tried setting the Content-Type like below: using (var httpClient = new HttpClient()) { httpClient.BaseAddress = new Uri("http://example.com/"); httpClient.DefaultRequestHeaders.…

Read More