OpenAPI (Swagger) Renderer for Sphinx

0.9.0 · active · verified Wed Apr 15

sphinxcontrib-openapi is a Sphinx extension that renders OpenAPI (formerly Swagger) specifications directly within Sphinx documentation. It leverages `sphinxcontrib-httpdomain` to provide an HTTP domain for describing RESTful HTTP APIs, avoiding the need to re-implement core functionality. It is actively maintained with its latest version 0.9.0 released in February 2026.

Warnings

gotcha Older 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.
Fix: Upgrade 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.
gotcha The `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.
Fix: Ensure `pip install sphinxcontrib-httpdomain` has been run and `'sphinxcontrib.httpdomain'` is in the `extensions` list in `conf.py`.
gotcha Specific 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.
Fix: Consult 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.
gotcha As 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.
Fix: Check 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.

Install

pip install sphinxcontrib-openapi Install latest version

Imports

sphinxcontrib.openapi
wrong:
```
import sphinxcontrib.openapi
```
correct:
```
extensions = ['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.

Quickstart

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:
"""

view raw JSON →