Sphinxcontrib-redoc

1.6.0 · maintenance · verified Sat Apr 11

Sphinxcontrib-redoc is a Sphinx extension that renders OpenAPI (formerly Swagger) specifications using the ReDoc library. It integrates interactive API documentation directly into Sphinx-generated documentation. The current version is 1.6.0, released in April 2020, indicating that the project is in a maintenance state with infrequent updates.

Warnings

breaking Version 1.6.0 dropped official support for Python 3.4. Ensure you are using Python 3.5 or newer.
Fix: Upgrade your Python environment to 3.5 or later.
gotcha ReDoc can experience performance issues when rendering very large or complex OpenAPI specifications, leading to slow page load times in the generated documentation.
Fix: Consider using ReDoc options like `lazy-rendering` or `native-scrollbars` in your `redoc` configuration to mitigate performance impact for large specs.
gotcha When `embed` is set to `True`, the extension currently does not support embedding OpenAPI specifications from external HTTP(s) links; only local file paths are supported for embedding.
Fix: For embedded specs, provide a local file path for the 'spec' option. For external specs, set `embed: False`.
gotcha As of Sphinx 8, subsequent builds may produce a `WARNING: Aborted attempted copy from ... redoc.js` message. While often harmless, it can clutter build logs.
Fix: Currently, there is no official fix from `sphinxcontrib-redoc`. You may need to ignore this warning or monitor upstream for updates.
gotcha The `redoc.js` library bundled with `sphinxcontrib-redoc` (last updated with v1.21.2 in 1.4.0, with minor updates up to 1.6.0) is potentially outdated. Newer ReDoc versions offer better features and bug fixes.
Fix: Override the `redoc_uri` Sphinx option to point to a more current ReDoc CDN, e.g., `redoc_uri = 'https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js'`.
gotcha The HTML page generated by `sphinxcontrib-redoc` is not automatically included in Sphinx's `toctree` (table of contents).
Fix: You must explicitly create a stub `.rst` file (e.g., `api.rst` or `api/index.rst`) and include it in your main `toctree` directive within your Sphinx project. This file will then be overwritten or used as the target for the ReDoc output.

Install

pip install sphinxcontrib-redoc Install with pip

Imports

sphinxcontrib.redoc
```
extensions = ['sphinxcontrib.redoc']
```
The extension is enabled by adding 'sphinxcontrib.redoc' to the 'extensions' list in Sphinx's conf.py.

Quickstart

To quickly integrate sphinxcontrib-redoc, first install the package. Then, enable the extension by adding 'sphinxcontrib.redoc' to the `extensions` list in your Sphinx `conf.py`. Define your OpenAPI specifications using the `redoc` configuration variable, which is a list of dictionaries. Each dictionary specifies the API's name, the output HTML page path, the path (local or URL) to the OpenAPI spec, and optional ReDoc rendering options. You must also create an RST file (e.g., `api/index.rst`) for each defined page to ensure it's included in Sphinx's table of contents and provides a target for the rendered documentation.

# conf.py
import os

project = 'My API Docs'
copyright = '2026, Your Name'
extensions = [
    'sphinxcontrib.redoc',
    'sphinx.ext.autodoc', # Example of another common extension
]

# Configure sphinxcontrib-redoc
redoc = [
    {
        'name': 'My Awesome API',
        'page': 'api/index', # Output HTML page path relative to build directory
        'spec': 'openapi.yaml', # Path to OpenAPI spec relative to conf.py
        'embed': True, # Embed the spec into the HTML page
        'opts': {
            'lazy-rendering': True,
            'native-scrollbars': True,
            'hide-hostname': True,
            'expand-responses': ['200', '201'],
        }
    },
]

# Example of a minimal index.rst or api/index.rst
# My Awesome API
# ==============
#
# .. toctree::
#    :maxdepth: 2
#
# .. raw:: html
#
#    <div id="redoc-container"></div>

# Make sure the openapi.yaml exists in your docs folder for a local spec.
# Or use a remote URL: 'spec': 'https://petstore.swagger.io/v2/swagger.json'

view raw JSON →