sphinxcontrib-openapi

What it is and what it does

sphinxcontrib-openapi is a Sphinx extension that converts OpenAPI (formerly Swagger) specification files into formatted API documentation. It leverages the sphinxcontrib-httpdomain extension to provide HTTP domain support, so it integrates naturally with Sphinx's documentation build pipeline. You add it to your Sphinx conf.py extensions list and then use the openapi directive to point to your spec file—typically a YAML or JSON OpenAPI definition—and it renders the endpoints, parameters, request/response schemas, and other API details into your documentation.

The package depends on Sphinx, PyYAML for parsing specs, jsonschema for validation, and a few utility libraries (picobox, deepmerge, sphinx-mdinclude) to handle configuration and schema merging. It's designed for teams that maintain OpenAPI specs and want to keep their API documentation in sync without manual rewriting.

Use it for:

• Generate API reference documentation from an OpenAPI spec as part of your Sphinx build process.
• Keep API docs automatically synchronized with your OpenAPI definition during development.
• Render REST endpoint details (paths, methods, parameters, responses) into a Sphinx project.
• Embed interactive or formatted API specifications into larger technical documentation.
• Build a single-source documentation site where API reference comes from your spec file.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Sphinx extension that renders OpenAPI (Swagger) specifications into formatted API documentation using the HTTP domain.

Yes, if you maintain an OpenAPI spec and use Sphinx for documentation. The package is stable, permissively licensed, and has low install friction. Maintenance is aging (185 days since last release), so verify compatibility with your Sphinx version before adopting. No known security vulnerabilities.

Install

sphinxcontrib-openapi on PyPI

pip install sphinxcontrib-openapi

uv add sphinxcontrib-openapi

poetry add sphinxcontrib-openapi

Installing sphinxcontrib-openapi

Before you install

Low friction install with a pure Python wheel. Maintenance is aging—last release 185 days ago—but the repository remains active and the package has been stable since its 2016 release.

License in practice

BSD-3-Clause is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install sphinxcontrib-openapi

# In conf.py:
extensions = [
    'sphinxcontrib.openapi',
]

# In your .rst file:
.. openapi:: path/to/openapi.yml

Requires Python 3.10 or later.

Verify before relying

• Whether the package handles all OpenAPI 3.0+ features or has known limitations with certain spec versions.
• Performance characteristics when rendering large or complex OpenAPI specifications.
• Compatibility with recent Sphinx versions beyond what the classifiers indicate.

Package facts

Evidence: sphinxcontrib_openapi-0.9.0-py3-none-any.whl

Keywords: sphinx, openapi, swagger, rest, api, renderer, docs

Tags

More Documentation packages