Install & Compatibility
Where this runs
tested against v0.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 99.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.7s · import 0.000s · 100MB
102MB installed
● package 102MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxcontrib.openapi
✓ extensions = ['sphinxcontrib.openapi']
✗ import sphinxcontrib.openapi
Sphinx extensions are activated by adding their string name to the 'extensions' list in `conf.py`, not by direct Python import in document source files.
To quickly use `sphinxcontrib-openapi`, first ensure it's added to the `extensions` list in your Sphinx project's `conf.py`. Then, create an OpenAPI specification file (e.g., `openapi.yml`) and use the `.. openapi::` directive in your reStructuredText files, pointing to the spec file. Optional parameters like `:paths:`, `:examples:`, and `:group:` can control what parts of the spec are rendered and how.
# conf.py
# Add 'sphinxcontrib.openapi' to your extensions list
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinxcontrib.httpdomain', # Ensure this is also included if not already
'sphinxcontrib.openapi'
]
# docs/api.rst
# Create a sample OpenAPI spec file at docs/specs/openapi.yml
# For example:
# swagger: "2.0"
# info:
# title: My API
# version: "1.0.0"
# paths:
# /greet:
# get:
# summary: Greet a user
# responses:
# 200:
# description: A greeting message
# In your .rst file, use the directive:
"""
API Documentation
=================
.. openapi:: specs/openapi.yml
:paths: /greet
:examples:
:group:
"""
Debug
Known issues
gotchaOlder versions of `sphinxcontrib-openapi` (prior to current `0.9.0`) have been reported to struggle with certain structures in OpenAPI 3.0.x specifications, particularly concerning response object nesting, and were more reliably compatible with Swagger 2.0. If encountering rendering issues with OpenAPI 3.x, ensure you are on the latest `sphinxcontrib-openapi` version.fixUpgrade to the latest version of `sphinxcontrib-openapi`. Review your OpenAPI 3.x spec for any complex or non-standard nesting that might trigger parsing issues.
affects: <=0.7.0 (prior to 0.9.0)
gotchaThe `sphinxcontrib-httpdomain` package is a mandatory dependency and must be installed and listed in your `conf.py` `extensions` list alongside `sphinxcontrib.openapi`. Failure to include it will result in `sphinxcontrib-openapi` not functioning correctly as it relies on its HTTP domain definitions.fixEnsure `pip install sphinxcontrib-httpdomain` has been run and `'sphinxcontrib.httpdomain'` is in the `extensions` list in `conf.py`.
affects: All versions
gotchaSpecific configuration options for the `openapi` directive, such as `:examples:` or filtering `paths`, might not always work as expected for all OpenAPI spec structures or can lead to incomplete rendering. For instance, issues have been reported where schema examples do not show or filtering with multiple paths fails.fixConsult the official documentation for the exact syntax and limitations of directive options. Simplify your OpenAPI spec or try rendering without the problematic options to isolate the issue. Check GitHub issues for known bugs related to your specific rendering problem.
affects: All versions (potential edge cases)
gotchaAs a Sphinx extension, `sphinxcontrib-openapi` can be affected by major breaking changes in Sphinx itself. Sphinx releases (e.g., Sphinx 9.0) often introduce incompatible changes to internal APIs that extensions rely on. Always test `sphinxcontrib-openapi` after upgrading Sphinx to a new major version.fixCheck the `sphinxcontrib-openapi` release notes or GitHub repository for compatibility statements with new Sphinx versions before upgrading Sphinx. Pin your Sphinx version if stability is critical.
affects: All versions, especially with new major Sphinx releases
Upgrade
Version history
0.9.0latest on PyPI · released Feb 10, 2026
Audit
Dependencies
SphinxrequiredCore documentation generation framework.
sphinxcontrib-httpdomainrequiredProvides the HTTP domain for describing RESTful APIs, which sphinxcontrib-openapi builds upon. This is a mandatory dependency.