RESTful web service API documentation with Sphinx

rest documentation python-sphinx
deceze picture deceze · Dec 28, 2010 · Viewed 10.3k times · Source

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

Viktor Haag picture Viktor Haag · Oct 3, 2011

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.

Related questions

Standard methods for documenting a RESTful API

I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding …

Read More
How to automate documentation of a REST API (Jersey Implementation)

I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, …

Read More
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