RESTful web service API documentation with Sphinx [closed]

Question

What's the best way to markup methods/URLs for a RESTful webservice using ReST/Sphinx? Is there a default domain that's suitable for marking up URLs with their possible parameters, HTTP methods, headers and body content?

Something along the lines of:

.. rest:method:: GET /api/foo     :param bar: A valid bar    :extension: json or xml     Retrieve foos for the given parameters. E.g.::        GET /api/foo.json?bar=baz 

Does something like this already exist or is one of the default extensions usable, or will I have to write one myself?

Answer 1

The Sphinx Contrib project also seems to have an HTTP Domain package for documenting RESTful HTTP APIs. You can find its documentation on the Python packages site. I can't speak to its fitness: I'm only just starting to look into Sphinx, and I have a need to document RESTful APIs as well, and noticed this contributed package.