5

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.

2
  • Why you need a text file with documentation to generate documentation? I mean, really, why don't you just write documentation in Open Office or something and save it as PDF, XML, etc? Other tools, like doxygen, are meant to generate documentation from source code and commentaries in it.
    – user405725
    Oct 14, 2010 at 20:05
  • Sorry, should've mentioned--I want to generate HTML files from it, but I'd rather not be editing HTML to generate it. I'm really just looking for a way to save the docs in a format with minimal formatting (using Markdown or something similar) and then transform that into a bunch of linked HTML files. Oct 14, 2010 at 20:07

3 Answers 3

4

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.

1
  • 1
    I think the key point is that there is really no standardized way of documenting a media type. If only there was. It certainly cannot be generated. Oct 14, 2010 at 23:37
0

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.

0

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.