Sphinx plugin to add an HTTP domain, allowing the documentation of RESTful HTTP methods.
You can document simple methods, wrap any arguments in the path with curly-braces:
.. http:method:: GET /api/foo/bar/{id}/{slug}
:arg id: An id
:arg slug: A slug
Retrieve list of foobars matching given id.Query string parameters are also supported, both mandatory and optional:
.. http:method:: GET /api/foo/bar/?id&slug
:param id: An id
:optparam slug: A slug
Search for a list of foobars matching given id.As well, you can provide types for parameters and arguments:
.. http:method:: GET /api/foo/bar/{id}/?slug
:arg integer id: An id
:optparam string slug: A slug
Search for a list of foobars matching given id.Fragments are also supported:
.. http:method:: GET /#!/username
:fragment username: A username
Renders a user's profile page.Plus, you can document the responses with their response codes:
.. http:method:: POST /api/foo/bar/
:param string slug: A slug
:response 201: A foobar was created successfully.
:response 400:
Create a foobar.To refer to an HTTP method, use :http:method::
.. http:method:: GET /api/
:label-name: get-root
:title: API root
The :http:method:`get-root` contains all of the API.Documenting responses is also simple:
.. http:response:: Foobar object
A foobar object looks like this::
.. source-code:: js
{
'slug': SLUG
}
:data string SLUG: A slug
:format: JSONTo refer to an HTTP response, use :http:response::
.. http:response:: Foobar object
A :http:response:`foobar-object` is returned when you foo the bar.Requires Sphinx >= 1.0.6 (http://sphinx.pocoo.org).
Run pip install sphinx-http-domain.
Then, add sphinx_http_domain to your conf.py:
extensions = ['sphinx_http_domain']- Version: 0.2
- Homepage: https://github.com/deceze/Sphinx-HTTP-domain
For contributions, please fork this project on GitHub!
David Zentgraf (https://github.com/deceze)
- Simon Law (https://github.com/sfllaw), who really wrote virtually all of this