Swagger Plugin for Sphinx
This is a handy plugin to bring Swagger and Sphinx together.
It can generate one or multiple swagger HTML pages with a custom configuration that hosts an OpenAPI specification.
Install
Just run pip install swagger-plugin-for-sphinx
Usage
Enable the Plugin
First, add the plugin to the extensions list:
extensions = ["swagger_plugin_for_sphinx"]
Global Configuration
Swagger uses two JavaScript and one CSS file to render the output.
These can be set in conf.py:
swagger_present_uri = ""
swagger_bundle_uri = ""
swagger_css_uri = ""
These correspond to the modules explained here. By default, the latest release is used from here.
Optionally if you do now want to redirect users to the mirror but prefer local
serving you can mirror the Swagger dependencies into the generated doctree in conf.py via:
swagger_mirror_external_resources = True
Directive
To include a Swagger API specification into an HTML page specify the swagger-plugin directive
and the relative path to the specification:
.. swagger-plugin:: path/to/spec.yaml
The spec is automatically copied into the _static build output directory.
The directive supports the following options
id: specifies an unique ID for the specification per page (see below)full-page: if set, all other content on the page is dropped and only the Swagger part is renderedpage-title: the name of the HTML page iffull-pageis specifiedswagger-options: JSON string that is passed to Swagger to enable additional options as described on the configuration page of the Swagger documentation.
By default, the directive creates a <div> element with the ID swagger-ui-container.
If you put more than one swagger-plugin directive in a file, specify unique IDs:
.. swagger-plugin:: path/to/one.yaml
:id: spec-one
.. swagger-plugin:: path/to/two.yaml
:id: spec-two
Development
This project uses uv.
To install uv, and setup a venv for development, use:
python3.14 -m venv venv && \
source venv/bin/activate && \
pip install uv && uv sync --all-groups && \
deactivate && \
rm -rf venv/
This will create a temporary venv, install uv to bootstrap the project
.venv, and remove the temporary venv again.
Then use source .venv/bin/activate to activate your venv.
Build and Publish
Execute the release action with the proper version.
Support, Feedback, Contributing
This project is open to feature requests/suggestions, bug reports etc., via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.
Code of Conduct
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.
Licensing
Copyright 2025 SAP SE or an SAP affiliate company and swagger-plugin-for-sphinx contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.
Release files for swagger-plugin-for-sphinx 7.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| swagger_plugin_for_sphinx-7.3.0.tar.gz | 143.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| swagger_plugin_for_sphinx-7.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 157.1 kB
Release files / swagger_plugin_for_sphinx-7.3.0.tar.gz
| Download URL | swagger_plugin_for_sphinx-7.3.0.tar.gz |
|---|---|
| Size | 143.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
53c3718f78979ade1b8763c1fe873b41ae398da149a0eeb79d3f633690d56d04
|
|
BLAKE2b-256 checksum How to use checksums |
d4b2fc7d3442134eff550fa1a718b96b20cc097ed369120373853360d3017d33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / swagger_plugin_for_sphinx-7.3.0-py3-none-any.whl
| Download URL | swagger_plugin_for_sphinx-7.3.0-py3-none-any.whl |
|---|---|
| Size | 13.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7be4e985767186fc5a11876026ebd2ceb010ea2fd5b33efe1b620306f59a3e56
|
|
BLAKE2b-256 checksum How to use checksums |
a9ef5839baafa9e084af6696a13dd7993d2ec1f6e5cd58667f56f37ad61cf6b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency log
