Sphinx HTTP Domain

2.0.0 · active · verified Fri Apr 10

Sphinxcontrib-httpdomain is an active Sphinx extension (current version 2.0.0) that provides a domain for documenting RESTful HTTP APIs directly within reStructuredText or MyST documentation. It allows authors to describe HTTP resources, methods, request/response headers, query parameters, and status codes, integrating API documentation seamlessly with project documentation. Releases are made as needed, often tied to Sphinx compatibility or feature additions.

Warnings

breaking Version 2.0.0 requires Python >=3.10. Users on older Python versions (e.g., 3.7-3.9) must upgrade their Python environment to use this version of the extension.
Fix: Upgrade your Python environment to 3.10 or newer, or pin to an older `sphinxcontrib-httpdomain` version (e.g., `<2.0.0`) if Python upgrade is not feasible.
deprecated The `mimetype` role was deprecated in version 1.3.0. Use the `http:header` role instead for referring to MIME types or HTTP headers.
Fix: Replace `:mimetype:` with `:http:header:` in your documentation. For example, `:mimetype:`text/html`` becomes `:http:header:`Content-Type```.
gotcha The `http_strict_mode` configuration option's behavior changed in version 1.5.0. It no longer warns on non-standard header prefixes, potentially leading to fewer warnings than expected if strict mode was relied upon for such validation.
Fix: Review your documentation and consider custom Sphinx validation if you relied on `http_strict_mode` for warnings about non-standard header prefixes.
gotcha Users have reported 'routingtable not defined' errors during parallel Sphinx builds, indicating potential issues with concurrency when building documentation with this extension.
Fix: If encountering parallel build errors, try disabling parallel builds in Sphinx (e.g., `make html -j1` or setting `num_workers = 1` in `conf.py`). Monitor GitHub issues for a permanent fix.

Install

pip install sphinxcontrib-httpdomain Install stable version

Imports

Extension Configuration
```
extensions = ['sphinxcontrib.httpdomain']
```
This is a Sphinx extension; it's enabled by adding its name to the 'extensions' list in Sphinx's conf.py, not by a Python import statement for direct use.

Quickstart

To use sphinxcontrib-httpdomain, first add 'sphinxcontrib.httpdomain' to the 'extensions' list in your Sphinx project's `conf.py`. Then, you can define HTTP API endpoints using directives like `.. http:get::` in your reStructuredText or MyST files, detailing paths, parameters, statuses, and examples.

Add `sphinxcontrib.httpdomain` to your `conf.py`:

```python
# conf.py
project = 'My API Docs'
copyright = '2026, Your Name'
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.httpdomain'
]
```

Then, in a reStructuredText file (e.g., `api.rst`):

```rst
.. http:get:: /users/(int:user_id)
   :synopsis: Get user profile

   Fetches the profile for a specific user.

   :param user_id: The ID of the user to retrieve.
   :type user_id: int
   :status 200: User profile retrieved successfully.
   :status 404: User not found.

   **Example request**:

   .. sourcecode:: http

      GET /users/123 HTTP/1.1
      Host: example.com
      Accept: application/json

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
          "id": 123,
          "name": "John Doe",
          "email": "john.doe@example.com"
      }
```

view raw JSON →