Metadata-Version: 2.4
Name: swagger-plugin-for-sphinx
Version: 7.1.0
Summary: Sphinx plugin which renders a OpenAPI specification with Swagger
Author-email: Kai Harder <kai.harder@sap.com>
License-Expression: Apache-2.0
Project-URL: Changelog, https://github.com/SAP/swagger-plugin-for-sphinx/blob/main/CHANGELOG.md
Project-URL: Issue Tracker, https://github.com/SAP/swagger-plugin-for-sphinx/issues
Keywords: sphinx,swagger,plugin,openapi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Typing :: Typed
Requires-Python: <4,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sphinx<10,>=8.0
Requires-Dist: jinja2~=3.0
Requires-Dist: docutils
Requires-Dist: typing_extensions~=4.5
Dynamic: license-file

[![REUSE status](https://api.reuse.software/badge/github.com/SAP/swagger-plugin-for-sphinx)](https://api.reuse.software/info/github.com/SAP/swagger-plugin-for-sphinx)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Coverage Status](https://coveralls.io/repos/github/SAP/swagger-plugin-for-sphinx/badge.svg)](https://coveralls.io/github/SAP/swagger-plugin-for-sphinx)

# Swagger Plugin for Sphinx

This is a handy plugin to bring [Swagger](https://swagger.io/) and [Sphinx](https://www.sphinx-doc.org/en/master/) 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:

```python
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``:

```python
swagger_present_uri = ""
swagger_bundle_uri = ""
swagger_css_uri = ""
```

These correspond to the modules explained [here](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md).
By default, the latest release is used from [here](https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest).

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:

```python
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:

```code
.. 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](https://swagger.io/docs/open-source-tools/swagger-ui/usage/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:

```code
.. swagger-plugin:: path/to/one.yaml
   :id: spec-one

.. swagger-plugin:: path/to/two.yaml
   :id: spec-two
```

## Development
This project uses `uv`.
To setup a venv for development use
`python3.14 -m venv venv && pip install uv && uv sync --all-groups && rm -rf venv/`.
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](https://github.com/SAP/<your-project>/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](CONTRIBUTING.md).

## 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](CODE_OF_CONDUCT.md) at all times.

## Licensing

Copyright 2025 SAP SE or an SAP affiliate company and swagger-plugin-for-sphinx contributors.
Please see our [LICENSE](LICENSE) for copyright and license information.
Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/<your-project>).
