Sphinx plugin which renders a OpenAPI specification with Swagger
Project description
Swagger Plugin for Sphinx
This is handy plugin to bring Swagger and Sphinx together.
It is able to generate one or multiple swagger HTML pages with a custom configuration which host an OpenAPI specification.
Install
Just run pip install swagger-plugin-for-sphinx
Usage
First, add the plugin to the extensions list:
extensions = ["swagger_plugin_for_sphinx"]
Then add the main configuration for swagger:
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.
As a last step, define the swagger configuration as followed:
swagger = [
{
"name": "Service API",
"page": "openapi",
"options": {
"url": "openapi.yaml",
},
}
]
Each item of the list will generate a new swagger HTML page.
The name
is the HTML page name and page
defines the file name without an extension. This needs to be included in the TOC.
The options
are then used for the SwaggerUIBundle
as defined here.
Please don't specify the dom_id
since it's hardcoded in the HTML page.
In the sphinx build, a HTML page is created and put into the _static
directory of the build.
If the specification is provided as a file, don't forget to copy it (e.g. by putting it into the html_static_path
).
To silence the warning toctree contains reference to nonexisting document
,, just put a dummy file with the same name as page
into the source folder.
Build and Publish
This project uses setuptools
as the dependency management and build tool.
To publish a new release, follow these steps:
- Update the version in the
pyproject.toml
- Add an entry in the changelog
- Push a new tag like
vX.X.X
to trigger the release
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 2022 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for swagger-plugin-for-sphinx-3.0.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1c4fcfcaec5ec608c8f3836ec8ff0afa9d21801c6920871c8e339d33705f0361 |
|
MD5 | 2a0be8bba53a05c73930e0ded7c2e3f0 |
|
BLAKE2b-256 | 83422b029e5b23b4e068f7f956e49f3aeef3a596672bce9aacdfc6fcda404d35 |
Hashes for swagger_plugin_for_sphinx-3.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a4ab71399606331fc1e8620e25e5abcfebdb4630baccaca8e93c7f2d0f52a1cf |
|
MD5 | 11096cfd23f53334cacd8cb3c4066364 |
|
BLAKE2b-256 | 8612315224ab64d423ea919cd148349be08512e8400599fd3f9c95b32f7ca303 |