swagger-plugin-for-sphinx 7.2.1

Sphinx plugin which renders a OpenAPI specification with Swagger

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 rendered
• page-title: the name of the HTML page if full-page is specified
• swagger-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.