sphinxcontrib.httpdomain — Sphinx domain for documenting HTTP APIs

Latest PyPI version Supported Python versions Documentation status Build status PyPI monthly downloads GitHub Sponsors

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

See also

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

Module sphinxcontrib.autohttp.flask

Reflection for Flask webapps.

Module sphinxcontrib.autohttp.flaskqref

Quick reference rendering with sphinxcontrib.autohttp.flask

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-']

Added in version 1.4.0.

Deprecated since version 1.5.0: strict mode no longer warns on non-standard header prefixes.

http_index_ignore_prefixes

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

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

Added in version 1.3.0.

http_index_shortname

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

http_index_shortname = 'api'

Added in version 1.3.0.

http_index_localname

Full index name which is used on index page:

http_index_localname = "My Project HTTP API"

Added 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

Added in version 1.4.0.

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:

If you want to reference the generated routing table, you can use:

:ref:`routingtable`

Added in version 1.8.0.

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.

Added 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.

Added in version 1.3.0.

Options

Added 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.

Added 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

Added 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

Added 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

Added in version 1.3.0.

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

Description of request header field.

Added in version 1.1.9.

responseheader, resheader, <header

Description of response header field.

Added 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

.. http:get:: /posts/(int:post_id)

   Fetches the post

   (...)

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:
GET /posts/(int: post_id)

Fetches the post

(…)

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 OK`

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.

If the HTTP header is known, the text is a hyperlink to a web reference of the specified header.

Known HTTP headers:

Added in version 1.3.0.

Changed in version 1.5.0: No longer emits warnings for unrecognized headers

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

Added 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)

User profile page.

Parameters:

  • user – user login name

Status Codes:
GET /(user)/posts/(int: post_id)

User’s post.

Parameters:

  • user – user login name

  • post_id – post unique id

Status Codes:
.. autoflask:: module:app

Added 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.

Added 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.

Note

It is worth noting that the names of endpoints that are applied to blueprints are prefixed with the blueprint’s name (e.g. blueprint.endpoint).

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.

blueprints

Only include specified blueprints in generated references.

Added in version 1.1.9.

undoc-blueprints

Excludes specified blueprints from generated references.

Added in version 1.1.8.

modules

Only include specified view modules in generated references.

For example:

.. autoflask:: yourwebapp:app
   :modules: yourwebapp.views.admin

will include only views in yourwebapp.views.admin module

Added in version 1.5.0.

undoc-modules

Excludes specified view modules from generated references.

Added in version 1.5.0.

undoc-static

Excludes a view function that serves static files, which is included in Flask by default.

order

Determines the order in which endpoints are listed. Currently only path is supported.

For example:

.. autoflask:: yourwebapp:app
   :endpoints:
   :order: path

will document all endpoints in the flask app, ordered by their route paths.

Added in version 1.5.0.

groupby

Determines the strategy to group paths. Currently only view is supported. Specified this will group paths by their view functions.

Added in version 1.6.0.

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.

Added in version 1.1.2.

sphinxcontrib.autohttp.flaskqref — Quick API reference for Flask app

Added in version 1.5.0.

This generates a quick API reference table for the route documentation produced by sphinxcontrib.autohttp.flask

To use it, both sphinxcontrib.autohttp.flask and sphinxcontrib.autohttp.flaskqref need to be added into the extensions of your configuration (conf.py) file:

extensions = ['sphinxcontrib.autohttp.flask',
              'sphinxcontrib.autohttp.flaskqref']
.. qrefflask:: module:app

Added in version 1.5.0.

Generates HTTP API references from a Flask application and places these in a list-table with quick reference links. The usage and options are identical to that of sphinxcontrib.autohttp.flask with the addition of the autoquickref option.

Basic usage

You typically would place the quick reference table near the top of your docco and use .. autoflask:: further down.

Unless you use the autoquickref option, routes that are to be included in the quick reference table require the following rst comment to be added to their doc string:

.. :quickref: [<resource>;] <short description>

<resource> is optional, if used a semi-colon separates it from <short description> The table is grouped and sorted by <resource>.

<resource>

This is the resource name of the operation. The name maybe the same for a number of operations and enables grouping these together.

<short description>

A brief description what the operation does.

If you use the autoquickref option, all routes must be inside blueprints. The <resource> will be set to the blueprint’s name, and the <short description> will be set to the first line of the docstring.

For example:

@app.route('/<user>')
def user(user):
    """User profile page.

    .. :quickref: User; Get Profile Page

    my docco here
    """
    return 'hi, ' + user

The quick reference table is defined as:

.. qrefflask:: autoflask_sampleapp:app
   :undoc-static:

Using the autoflask_sampleapp with .. :quickref: annotations, this is rendered as:

Resource

Operation

Description

Home

GET /

The Home page

User

GET /(user)

Get Profile Page

GET /(user)/posts/(int:post_id)

Save user id

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:

GET /

Home page.

GET /(user)

User profile page.

Parameters:

  • user – user login name

Status Codes:
GET /(user)/posts/(post_id: int)

User’s post.

Parameters:

  • user – user login name

  • post_id – post unique id

Status Codes:
.. 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 bottle 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.

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.

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:

GET /

Home page.

GET /(?P<user>[a-z0-9]+)

User profile page.

Parameters:

  • user – user login name

Status Codes:
GET /(?P<user>[a-z0-9]+)/posts/(?P<post_id>[\d+]+)

User’s post.

Parameters:

  • user – user login name

  • post_id – post unique id

Status Codes:
.. 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.get, User.post, Friends.get

will document the get() and post() methods of the User RequestHandler and the get() method of the Friend RequestHandler, while

.. autotornado:: yourwebapp:app
   :endpoints:

will document all endpoints in the tornado 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.

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.

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.

The source code is maintained under the sphinx-contrib project in the httpdomain repository

$ git clone https://github.com/sphinx-contrib/httpdomain.git
$ cd httpdomain
orphan:

Changelog

Version 2.0.0

unreleased

Breaking changes

  • Dropped support for Python 3.9 and older. [pull request #85 by @stevepiercy]

  • Switched to implicit (native) namespace for sphinxcontrib. [pull request #75 by @icemac]

Major changes

  • Added support for Python 3.10 up to 3.14.[pull request #85 by @stevepiercy]

  • Adjusted a unit test regular expression for bottle_test.py. [pull request #85 by @stevepiercy]

  • Use MDN documentation for information about HTTP status codes instead of w3.org. [pull request #78 by @jamesrobson-secondmind]

Internal

  • Added Dependabot configuration. [pull request #85 by @stevepiercy]

  • Replaced Travis CI with GitHub workflows for continuous integration checks. [pull request #85 by @stevepiercy]

  • Dropped dependency on six libary. [pull request #72 by @WAKayser]

  • Updated translations for FR and ES languages. [pull request #77 by @nils-van-zuijlen]

  • Reorganized the repository structure to modern standards. This included moving source files into a src directory, renaming doc to docs, and other refinements. [pull request #91 by @stevepiercy]

  • Replaced setuptools with pyproject.toml configuration for modern project management. [pull request #91 by @stevepiercy]

  • Changed to use uv for development and continuous integration. [pull request #91 by @stevepiercy]

  • Moved the Makefile from the documentation directory to the root of the repository, and added a suite of commands for development and testing the package. [pull request #91 by @stevepiercy]

Documentation

  • Simplified and updated documentation requirements in rtd-requires.txt. [pull request #85 by @stevepiercy]

  • Added a .readthedocs.yaml configuration for Read the Docs builds. [pull request #85 by @stevepiercy]

  • Added omitted change log entries for v1.8.1. [pull request #85 by @stevepiercy]

  • Adjusted Sphinx configuration and example regex usage in conf.py. [pull request #85 by @stevepiercy]

  • Added CONTRIBUTING.md to encourage contributions. [pull request #91 by @stevepiercy]

  • Fixed broken links and redirecting links. [pull request #91 by @stevepiercy]

Version 1.8.1

Released on November 14, 2022

  • Add translations for French and Spanish. [pull request #57 by @olivier-heurtier]

  • multicore: Fix false positive warnings in merge_domaindata. [pull request #59 by Ryan Northey]

  • Copy parse_rule since it was removed in werkzeug 2.2. [pull request #61 by Ash Berlin-Taylor]

  • Update URLs for RFCs. [pull request #63 by Michal Čihař]

Version 1.8.0

Released on September 23, 2020

  • Make the generated routing table referencable using the ‘routingtable’ label. [pull request #19 by David Douard]

  • Add support for parallel sphinx builds. Increases sphinx version requirement to 1.6 [pull request #31 by Daniel Hofmann]

  • Remove references to the generic :py:obj: role [pull request #54 by Stephen Finucane]

  • Remove imports and calls to deprecated function force_decode who was removed starting with sphinx 4.0 [pull request #49 by Florian Masy]

  • Be explicit about what versions of Python are supported (2.7, and 3.5+). This will be the last version to support Python 2.7 and 3.5, version 2.0 will require 3.6+.

Version 1.7.0

Released on July 1, 2018.

Version 1.6.1

Released on March 3, 2018.

Version 1.6.0

Released on January 13, 2018.

Version 1.5.0

Released on May 30, 2016.

Version 1.4.0

Released on August 13, 2015.

Version 1.3.0

Released on July 31, 2014.

Version 1.2.1

Released on March 31, 2014.

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.

Version 1.1.7

Released on March 28, 2012.

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. [old pull request #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.