11 Oct 2016 by dryobates
Many REST frameworks have built in documentation for provided API. Many specialized software exists for centralized API documentation. But if all you need is to include documentation for your project in your regular sphinx documentation then sphinxcontrib-httpdomain can be helpful.
sphinxcontrib-httpdomain has a lot roles and directives for providing documentation for rest api. It has also autodoc support for Flask, Bottle and Tornado.
We use Flask, so here's quick example, how much you can get with it.
And the result is:
In the above source code I have written examples by hand. That's only to show what can be done. Personally I'd prefer to pass link to source code of test. Probably doctest could be even better. I have to explore that idea for API requests.
One thing that doesn't look good for me is description of JSON. We use jsonschema and can generate it on the fly. I don't know how to include it in documentation. The only extension for jsonschema I found is sphinxcontrib-jsonschema but it can only read schema from file :( Do you know something better?