What's the best way to generate a REST API's documentation?

Question

I'm looking for a nice way to generate documentation for a REST API. It doesn't need to actually connect with the code or anything, but it'd be awesome to be able to write the documentation as text files, point the tool at it, and generate some docs from it.

Anyone out there have any ideas? I know I'm being a bit vague, but, to be honest, I'm not quite sure what I'm looking for here--mainly an easy way to manage documentation.

Answer 1

Hmm, groff/troff come to mind (used for man pages), as does latex (great if you have math equations and imagery etc) and docbook.

I'd personally lean toward LaTex, but then I've never generated seperate linked html files from it.

But the real biggy here is probably the programming language you use to generate the api, if you're lucky it will have a commenting format which you can run a tool against and generate documentation directly from there.

Java, C++ and C# at least are covered in this regard. (JavaDoc, CppDoc, ...)

Answer 2

According to Roy:

"A REST API should spend almost all of its descriptive
 effort in defining the media type(s) used for representing
 resources and driving application state, or in defining
 extended relation names and/or hypertext-enabled mark-up
 for existing standard media types."

Self-descriptiveness is one of the benefits of REST.

Answer 3

While not REST, I used Sphinx to document an XML-RPC API that consisted of an API reference and a tutorial. Sphinx adds some handy directives to ReStructuredText to get pretty much what you asked for: a collection of ReStructuredText formatted-text files that Sphinx turns into HTML and PDFs, complete with an index and table of contents. Sphinx is easy to use and well-documented; I don't think it would be an exaggeration to say you could get started with it in about ten minutes.

Answer 4

Some RESTful systems are actually able to write their own API. Have a look at RESTx, which does just that: You write your components and then create new web services by sending parameters for those components to the server (either as JSON or via a web form). You then get a URI back for those parameters. Accessing it calls the component with the parameters and you retrieve the results.

At any rate, the components as well as the created RESTful web services get an automatically generated documentation, which is browseable and can be retrieved either in HTML or JSON format.