This contrib extension, sphinxcontrib.httpdomain, provides a Sphinx domain for describing RESTful HTTP APIs.
See also
If your webapp is powered by Flask? See sphinxcontrib.autohttp.flask also.
In order to use it, add sphinxcontrib.httpdomain into extensions list of your Sphinx configuration file (conf.py):
extensions = ['sphinxcontrib.httpdomain']
There are several provided directives that describe HTTP resources.
.. http:get:: /users/(int:user_id)/posts/(tag)
The posts tagged with `tag` that the user (`user_id`) wrote.
**Example request**:
.. sourcecode:: http
GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
[
{
"post_id": 12345,
"author_id": 123,
"tags": ["server", "web"],
"subject": "I tried Nginx"
},
{
"post_id": 12346,
"author_id": 123,
"tags": ["html5", "standards", "web"],
"subject": "We go to HTML 5"
}
]
:query sort: one of ``hit``, ``created-at``
:query offset: offset number. default is 0
:query limit: limit number. default is 30
:statuscode 200: no error
:statuscode 404: there's no user
will be rendered as:
- GET /users/(int: user_id)/posts/(tag)¶
The posts tagged with tag that the user (user_id) wrote.
Example request:
GET /users/123/posts/web HTTP/1.1 Host: example.com Accept: application/json, text/javascriptExample response:
HTTP/1.1 200 OK Vary: Accept Content-Type: text/javascript [ { "post_id": 12345, "author_id": 123, "tags": ["server", "web"], "subject": "I tried Nginx" }, { "post_id": 12346, "author_id": 123, "tags": ["html5", "standards", "web"], "subject": "We go to HTML 5" } ]
Query Parameters:
- sort – one of hit, created-at
- offset – offset number. default is 0
- limit – limit number. default is 30
Status Codes:
- 200 – no error
- 404 – there’s no user
Of course, roles that refer the directives as well. For example:
:http:get:`/users/(int:user_id)/posts/(tag)`
will render like:
Describes a HTTP resource’s OPTIONS method. It can also be referred by http:options role.
Describes a HTTP resource’s HEAD method. It can also be referred by http:head role.
Describes a HTTP resource’s POST method. It can also be referred by http:post role.
Describes a HTTP resource’s GET method. It can also be referred by http:get role.
Describes a HTTP resource’s PUT method. It can also be referred by http:put role.
Describes a HTTP resource’s PATCH method. It can also be referred by http:patch role.
Describes a HTTP resource’s DELETE method. It can also be referred by http:delete role.
Describes a HTTP resource’s TRACE method. It can also be referred by http:trace role.
Inside HTTP resource description directives like get, reStructuredText field lists with these fields are recognized and formatted nicely:
Description of a parameter passed by request content body, encoded in application/json.
New in version 1.1.8.
For example:
.. http:post:: /posts/(int:post_id)
Replies a comment to the post.
:param post_id: post's unique id
:type post_id: int
:form email: author email address
:form body: comment body
:status 302: and then redirects to :http:get:`/posts/(int:post_id)`
:status 400: when form parameters are missing
It will render like this:
- POST /posts/(int: post_id)¶
Replies a comment to the post.
Parameters:
- post_id (int) – post’s unique id
Form Parameters:
- email – author email address
- body – comment body
Status Codes:
- 302 – and then redirects to GET /posts/(int:post_id)
- 400 – when form parameters are missing
Refers to the http:options directive.
Refers to the http:patch directive.
Refers to the http:delete directive.
Refers to the http:trace directive.
A reference to a HTTP status code. The text “code Status Name” is generated; in the HTML output, this text is a hyperlink to a web reference of the specified status code.
For example:
- :http:statuscode:`404`
- :http:statuscode:`200 Oll Korrect`
will be rendered as:
A reference to a HTTP method (also known as verb). In the HTML output, this text is a hyperlink to a web reference of the specified HTTP method.
For example:
It accepts :http:method:`post` only.
It will render like this:
It accepts POST only.
Exactly it doesn’t belong to HTTP domain, but standard domain. It refers to the MIME type like text/html.
New in version 1.1.
It generates RESTful HTTP API reference documentation from a Flask application’s routing table, similar to sphinx.ext.autodoc.
In order to use it, add sphinxcontrib.autohttp.flask into extensions list of your Sphinx configuration (conf.py) file:
extensions = ['sphinxcontrib.autohttp.flask']
For example:
.. autoflask:: autoflask_sampleapp:app
:undoc-static:
will be rendered as:
- GET /¶
Home page.
- GET /(user)/posts/(int: post_id)¶
User’s post.
Parameters:
- user – user login name
- post_id – post unique id
Status Codes:
- 200 – when user and post exists
- 404 – when user and post doesn’t exist
- GET /(user)¶
User profile page.
Parameters:
- user – user login name
Status Codes:
- 200 – when user exists
- 404 – when user doesn’t exist
New in version 1.1.
Generates HTTP API references from a Flask application. It takes an import name, like:
your.webapplication.module:app
Colon character (:) separates module path and application variable. Latter part can be more complex:
your.webapplication.module:create_app(config='default.cfg')
It’s useful when a Flask application is created from the factory function (create_app(), in the above example).
It takes several flag options as well.
Endpoints to generate a reference.
.. autoflask:: yourwebapp:app
:endpoints: user, post, friends
will document user(), post(), and friends() view functions, and
.. autoflask:: yourwebapp:app
:endpoints:
will document all endpoints in the flask app.
For compatibility, omitting this option will produce the same effect like above.
New in version 1.1.8.
Excludes specified endpoints from generated references.
For example:
.. autoflask:: yourwebapp:app
:undoc-endpoints: admin, admin_login
will exclude admin(), admin_login() view functions.
Note
While the undoc-members flag of sphinx.ext.autodoc extension includes members without docstrings, undoc-endpoints option has nothing to do with docstrings. It just excludes specified endpoints.
Excludes specified blueprints from generated references.
New in version 1.1.8.
View functions that don’t have docstring (__doc__) are excluded by default. If this flag option has given, they become included also.
New in version 1.1.2.
The sphinxcontrib.httpdomain and sphinxcontrib.autohttp, parts of sphinxcontrib, are written by Hong Minhee and distributed under BSD license.
The source code is mantained under the common repository of contributed extensions for Sphinx (find the httpdomain directory inside the repository).
$ hg clone https://bitbucket.org/birkenfeld/sphinx-contrib
$ cd sphinx-contrib/httpdomain
Released on April 10, 2013.
Released on March 28, 2012.
Released on December 16, 2011.
Released on July 6, 2011.
Released on June 2, 2011. The first release.