Provides the swaggerui directive for reST files to build an interactive HTML page with your OpenAPI specification document.
Project description
Provides the swaggerui directive for reST files to build a driven by Swagger-UI interactive panel presenting your OpenAPI specification document.
Overview
This Sphinx extension is necessary for those who publish an interactive document presenting their API specification compliant with OpenAPI and want to use the well-known Swagger-UI tool for this purpose. The swaggerui directive enables you to embed such interactive panel in an arbitrary place of a reST file.
Sphinx Directive swaggerui
Installation
$ pip install sphinxcontrib-swaggerui
Configuration
In your Sphinx project configuration file conf.py, add the installed extension:
extensions = [..., 'sphinxcontrib.swaggerui', ...]
The directive also implies that you use the static content in the _static/ folder and this is configured as:
html_static_path = ['_static']
Directive in reST Files
Use the following sample configuration (containing all possible options) when testing the directive for the first time:
.. swaggerui:: ../_static/swaggerui/petstore.yaml # *) Required :url: https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js # *) Required :css: ../_static/swaggerui/swagger-ui.css # *) Required :script: https://unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js # Optional :filter: pets # Optional
An attribute (for example, ../_static/swagger/petstore.yaml) refers to your local YAML or JSON file in the OpenAPI format. The path must be relative to the document containing the directive.
The directive uses the following options:
url refers to a CDN-based (Content Delivery Network) Swagger-UI package. For a proper version of the script, refer to the UNPKG CDN. The script name must be swagger-ui-bundle.js.
css refers to a local Swagger-UI CSS file. The path must be relative to the document containing the directive. You can find a proper CSS file in the UNPKG CDN.
script refers to an additional script (the one in the above example is recommended). For a proper version of the script, refer to the UNPKG CDN. The script name must be swagger-ui-standalone-preset.js. Probably, you will find another script that can work with the main Swagger-UI script specified by the :url: option.
filter requires Swagger UI to display only those endpoints (paths) which contain a tag that partially or fully matches the filter.
Sample CSS Customization
Avoid the operation block tag to disappear:
h4.opblock-tag a.nostyle { opacity: 1 }
Remove the Swagger top-bar:
.swagger-ui .topbar { display: none; }
Links
Source: Bitbucket
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
Hashes for sphinxcontrib-swaggerui-0.0.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | accb44764e387f986c3bc99690d70e21d4d438ccc3fec6cdee18ec7d5c80ae99 |
|
MD5 | 76d9a9ed75d9262312474561063750f8 |
|
BLAKE2b-256 | cf03c973aa05ff6e3e8f0dcffc2d022769948edadf2e2d25ee81d68ad1d47c92 |