sphinxcontrib.httpdomain — Documenting RESTful HTTP APIs

This contrib extension, sphinxcontrib.httpdomain, provides a Sphinx domain for describing RESTful HTTP APIs.

See also

We might support reflection for web framework your webapp depends on. See the following sphinxcontrib.auttohttp modules:

Module sphinxcontrib.autohttp.flask
Reflection for Flask webapps.
Module sphinxcontrib.autohttp.bottle
Reflection for Bottle webapps.
Module sphinxcontrib.autohttp.tornado
Reflection for Tornado webapps.

In order to use it, add sphinxcontrib.httpdomain into extensions list of your Sphinx configuration file (conf.py): 

extensions = ['sphinxcontrib.httpdomain']

Additional Configuration

http_headers_ignore_prefixes

List of HTTP header prefixes which should be ignored in strict mode: 

http_headers_ignore_prefixes = ['X-']

New in version 1.3.1.

http_index_ignore_prefixes

Strips the leading segments from the endpoint paths by given list of prefixes: 

http_index_ignore_prefixes = ['/internal', '/_proxy']

New in version 1.3.0.

http_index_shortname

Short name of the index which will appears on every page: 

http_index_shortname = 'api'

New in version 1.3.0.

http_index_localname

Full index name which is used on index page: 

http_index_shortname = "My Project HTTP API"

New in version 1.3.0.

http_strict_mode

When True (default) emits build errors when status codes, methods and headers are looks non-standard: 

http_strict_mode = True

New in version 1.3.1.

Basic usage

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
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :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/javascript

Example 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
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – optional OAuth token to authenticate
Response Headers:
 
Status Codes:

Of course, roles that refer the directives as well. For example: 

:http:get:`/users/(int:user_id)/posts/(tag)`

will render like:

Directives

.. http:options:: path

Describes a HTTP resource’s OPTIONS method. It can also be referred by http:options role.

.. http:head:: path

Describes a HTTP resource’s HEAD method. It can also be referred by http:head role.

.. http:post:: path

Describes a HTTP resource’s POST method. It can also be referred by http:post role.

.. http:get:: path

Describes a HTTP resource’s GET method. It can also be referred by http:get role.

.. http:put:: path

Describes a HTTP resource’s PUT method. It can also be referred by http:put role.

.. http:patch:: path

Describes a HTTP resource’s PATCH method. It can also be referred by http:patch role.

.. http:delete:: path

Describes a HTTP resource’s DELETE method. It can also be referred by http:delete role.

.. http:trace:: path

Describes a HTTP resource’s TRACE method. It can also be referred by http:trace role.

.. http:copy:: path

Describes a HTTP resource’s COPY method. It can also be referred by http:copy role.

New in version 1.3.0.

.. http:any:: path

Describes a HTTP resource’s which accepts requests with any method. Useful for cases when requested resource proxying the request to some other location keeping original request context. It can also be referred by http:any role.

New in version 1.3.0.

Options

New in version 1.3.0.

Additionally, you may specify custom options to the directives:

noindex

Excludes specific directive from HTTP routing table. 

.. http:get:: /users/(int:user_id)/posts/(tag)
   :noindex:
deprecated

Marks the method as deprecated in HTTP routing table. 

.. http:get:: /users/(int:user_id)/tagged_posts
   :deprecated:
synopsis

Adds short description for HTTP routing table. 

.. http:get:: /users/(int:user_id)/posts/(tag)
   :synopsis: Returns posts by the specified tag for the user

Resource Fields

Inside HTTP resource description directives like get, reStructuredText field lists with these fields are recognized and formatted nicely:

param, parameter, arg, argument
Description of URL parameter.
queryparameter, queryparam, qparam, query

Description of parameter passed by request query string.

It optionally can be typed, all the query parameters will have obviously string types though. But it’s useful if there’s conventions for it.

Changed in version 1.1.9: It can be typed e.g.: 

:query string title: the post title
:query string body: the post body
:query boolean sticky: whether it's sticky or not
formparameter, formparam, fparam, form
Description of parameter passed by request content body, encoded in application/x-www-form-urlencoded or multipart/form-data.
jsonparameter, jsonparam, json

Description of a parameter passed by request content body, encoded in application/json.

Deprecated since version 1.3.0: Use reqjsonobj/reqjson/<jsonobj/<json and reqjsonarr/<jsonarr instead.

New in version 1.1.8.

Changed in version 1.1.9: It can be typed e.g.: 

:jsonparam string title: the post title
:jsonparam string body: the post body
:jsonparam boolean sticky: whether it's sticky or not
reqjsonobj, reqjson, <jsonobj, <json

Description of a single field of JSON object passed by request body, encoded in application/json. The key difference from json is explicitly defined use-case (request/response) of the described object. 

:<json string title: the post title
:<json string body: the post body
:<json boolean sticky: whether it's sticky or not

New in version 1.3.0.

resjsonobj, resjson, >jsonobj, >json

Description of a single field of JSON object returned with response body, encoded in application/json. 

:>json boolean ok: Operation status

New in version 1.3.0.

reqjsonarr, <jsonarr resjsonarr, >jsonarr

Similar to <json and >json respectively, but uses for describing objects schema inside of returned array.

Let’s say, the response contains the following data:

[{"id": "foo", "ok": true}, {"id": "bar", "error": "forbidden", "reason": "sorry"}]

Then we can describe it in the following way:

:>jsonarr boolean ok: Operation status. Not present in case of error
:>jsonarr string id: Object ID
:>jsonarr string error: Error type
:>jsonarr string reason: Error reason

New in version 1.3.0. 

:>json boolean status: Operation status
requestheader, reqheader, >header

Description of request header field.

New in version 1.1.9.

responseheader, resheader, <header

Description of response header field.

New in version 1.1.9.

statuscode, status, code
Description of response status code.

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
   :reqheader Accept: the response content type depends on
                      :mailheader:`Accept` header
   :reqheader Authorization: optional OAuth token to authenticate
   :resheader Content-Type: this depends on :mailheader:`Accept`
                            header of request
   :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
Request Headers:
 
  • Accept – the response content type depends on Accept header
  • Authorization – optional OAuth token to authenticate
Response Headers:
 
Status Codes:

Roles

:http:options:

Refers to the http:options directive.

:http:head:

Refers to the http:head directive.

:http:post:

Refers to the http:post directive.

:http:get:

Refers to the http:get directive.

:http:put:

Refers to the http:put directive.

:http:patch:

Refers to the http:patch directive.

:http:delete:

Refers to the http:delete directive.

:http:trace:

Refers to the http:trace directive.

:http:copy:

Refers to the http:copy directive.

:http:any:

Refers to the http:any directive.

:http:statuscode:

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:

Changed in version 1.3.0: It becomes to provide references to specification sections.

:http:method:

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.
:mimetype:

Exactly it doesn’t belong to HTTP domain, but standard domain. It refers to the MIME type like text/html.

:mailheader:

Deprecated since version 1.3.0: Use http:header instead.

:http:header:

Similar to mimetype role, it doesn’t belong to HTTP domain, but standard domain. It refers to the HTTP request/response header field like Content-Type.

Known HTTP headers:

If HTTP header is unknown, the build error will be raised unless header has X- prefix which marks him as custom one like X-Foo-Bar.

New in version 1.3.0.

sphinxcontrib.autohttp.flask — Exporting API reference from Flask app

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:
GET /(user)

User profile page.

Parameters:
  • user – user login name
Status Codes:
.. autoflask:: module:app

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

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.

undoc-endpoints

Excludes specified endpoints from generated references.

For example:

.. autoflask:: yourwebapp:app
   :undoc-endpoints: admin, admin_login

will exclude admin(), admin_login() view functions.

blueprints

Only include specified blueprints in generated references.

New in version 1.1.9.

undoc-blueprints

Excludes specified blueprints from generated references.

New in version 1.1.8.

undoc-static
Excludes a view function that serves static files, which is included in Flask by default.
include-empty-docstring

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.

sphinxcontrib.autohttp.bottle — Exporting API reference from Bottle app

It generates RESTful HTTP API reference documentation from a Bottle application’s routing table, similar to sphinx.ext.autodoc.

In order to use it, add sphinxcontrib.autohttp.bottle into extensions list of your Sphinx configuration (conf.py) file: 

extensions = ['sphinxcontrib.autohttp.bottle']

For example:

.. autobottle:: autobottle_sampleapp:app

will be rendered as:

.. autobottle:: module:app

Generates HTTP API references from a Bottle 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 Bottle application is created from the factory function (create_app(), in the above example).

It takes several flag options as well.

endpoints

Endpoints to generate a reference.

.. autobottle:: yourwebapp:app
   :endpoints: user, post, friends

will document user(), post(), and friends() view functions, and 

.. autobottle:: yourwebapp:app
   :endpoints:

will document all endpoints in the flask app.

For compatibility, omitting this option will produce the same effect like above.

undoc-endpoints

Excludes specified endpoints from generated references.

For example:

.. autobottle:: yourwebapp:app
   :undoc-endpoints: admin, admin_login

will exclude admin(), admin_login() view functions.

include-empty-docstring
View functions that don’t have docstring (__doc__) are excluded by default. If this flag option has given, they become included also.

sphinxcontrib.autohttp.tornado — Exporting API reference from Tornado app

It generates RESTful HTTP API reference documentation from a Tornado application’s routing table, similar to sphinx.ext.autodoc.

In order to use it, add sphinxcontrib.autohttp.tornado into extensions list of your Sphinx configuration (conf.py) file: 

extensions = ['sphinxcontrib.autohttp.tornado']

For example:

.. autotornado:: autotornado_sampleapp:app

will be rendered as:

.. autotornado:: module:app

Generates HTTP API references from a Tornado application. It takes an import name, like: 

your.webapplication.module:app

Colon character (:) separates module path and application variable.

It takes several flag options as well.

endpoints

Endpoints to generate a reference.

.. autotornado:: yourwebapp:app
   :endpoints: user, post, friends

will document user(), post(), and friends() view functions, and 

.. autotornado:: yourwebapp:app
   :endpoints:

will document all endpoints in the flask app.

For compatibility, omitting this option will produce the same effect like above.

undoc-endpoints

Excludes specified endpoints from generated references.

For example:

.. autotornado:: yourwebapp:app
   :undoc-endpoints: admin, admin_login

will exclude admin(), admin_login() view functions.

include-empty-docstring
View functions that don’t have docstring (__doc__) are excluded by default. If this flag option has given, they become included also.

Author and License

The sphinxcontrib.httpdomain and sphinxcontrib.autohttp, parts of sphinxcontrib, are written by Hong Minhee and distributed under BSD license. 

$ hg clone https://bitbucket.org/birkenfeld/sphinx-contrib
$ cd sphinx-contrib/httpdomain

Changelog

Version 1.3.0

Released on July 31, 2014.

Version 1.2.1

Released on March 31, 2014.

  • Fixed broken Python 2.6 compatibility. [:pull:`41` by Kien Pham]

Version 1.2.0

Released on October 19, 2013.

Version 1.1.9

Released on August 8, 2013.

Version 1.1.8

Released on April 10, 2013.

  • Added better support for docstrings in flask.views.MethodView. [:pull:`26` by Simon Metson]
  • Added :jsonparameter: along side :form: and :query: flag options. [:pull:`25` by Adam Lowry]
  • Fixed issue with undefined Value and umethod variables. [:pull:`23` by Sebastian Kalinowski and :pull:`24` by Viktor Haag]
  • Now http Pygments lexer can Handle continuous header lines well.
  • Added :undoc-blueprints: flag option to autoflask directive. [:pull:`21` by Roman Podolyaka]
  • Fixed :issue:`29`, a bug that autoflask directive raised UnicodeDecodeError when it contains non-ASCII characters. [:issue:`29` and :pull:`18` by Eunchong Yu]
  • Added :endpoints: flag option to autoflask directive. [:pull:`17` by Eunchong Yu]

Version 1.1.7

Released on March 28, 2012.

  • Added PATCH method support. See http:patch role and http:patch directive. [:pull:`9` and :pull:`10` by Jeffrey Finkelstein]
  • The HTTP routing table can be grouped based on prefix by specifying http_index_ignore_prefixes config in list of common prefixes to ignore. [:pull:`7` and :pull:`8` by Andrey Popp]
  • The order of HTTP routing table now provides sorting by path as key. Previously it was sorted by HTTP method and then by path, which is non-intuitive. [:pull:`7` and :pull:`8` by Andrey Popp]

Version 1.1.6

Released on December 16, 2011.

  • Added http custom lexer for Pygments so that HTTP sessions can be highlighted in code-block or sourcecode directives.

Version 1.1.5

Released on July 6, 2011.

  • Flask 0.6–0.7 compatibility. Flask renamed static_path attribute to static_url_path, so autoflask also reflect the change. [:pull:`1` by Jeffrey Finkelstein]

Version 1.1.4

Released on June 8, 2011.

  • CPython compatibility
  • PyPy compatibility

Version 1.1.3

Released on June 8, 2011.

  • PyPy compatibility

Version 1.1.2

Released on June 4, 2011.

  • Added :include-empty-docstring: flag option.

Version 1.1.1

Released on June 4, 2011.

  • Fixed a backward incompatibility bug.

Version 1.1

Released on June 4, 2011.

Version 1.0

Released on June 2, 2011. The first release.