---
id: sphinxcontrib-openapi
version: "0.9.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: aging
---

# sphinxcontrib-openapi — OpenAPI (fka Swagger) spec renderer for Sphinx

License: permissive · Maintenance: aging · Downloads: 320.3K/mo

## 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 above — 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

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

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 320.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

openapi documentation generator, swagger spec to sphinx docs, rest api documentation sphinx, openapi renderer sphinx, generate api docs from openapi, sphinx openapi extension, api-documentation, openapi, sphinx-extension

[View on SkillFed](https://skillfed.io/packages/sphinxcontrib-openapi) · [View on PyPI](https://pypi.org/project/sphinxcontrib-openapi/)