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.
Sphinx Directive swaggerui
Installation
$ pip install sphinxcontrib-swaggerui
Configuration
In your project 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 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
The 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 this 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 the 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.
This package contains petstore.yaml and swagger-ui.css files (mentioned in the above example) copied to the _static/swaggerui/ folder during the first use of the directive by Sphinx. So don't care about copying these files when you specify the relative path to that folder; the sample files will appear automatically in it whether you use them or not.
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;
}
More complex customization that removes all headers leaving only the list of operations: GET, PUT, etc. - and does some other makeups:
/* Editing Swagger UI styles */
.topbar, .information-container, .scheme-container, .operation-filter-input, .try-out, .response-controls, .opblock-tag {
display: none!important;
}
.swagger-ui .response-col_description {
width: 75%!important;
}
.swagger-ui .response-col_links {
max-width: 100em;
}
.swagger-ui.swagger-container {
padding-top: 5px;
background-color: #EEF1F6;
}
This is how a section looks like with the above CSS:
![Image](./images/petstore-styled.png =600x)
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
Built Distribution
Hashes for sphinxcontrib_swaggerui-0.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9f1933beabed1cb7a1a8e60e78bbbe68a733018de460bf58a252ad6480b49db1 |
|
MD5 | 5ab25ab9adb14034df8803c9de34c681 |
|
BLAKE2b-256 | 1c468efff8a207675d405c22742dcbf82a79e3478e3c39e382f14c79e799b8ca |
Hashes for sphinxcontrib_swaggerui-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c91df8d78edb9a934f55f35b195b10fe20abeb3dd3a46b844be36221b656251d |
|
MD5 | 2a0cbf3ea07bbe358f5906d4f466dc78 |
|
BLAKE2b-256 | 4781774256116326df482a40b04b4879a44d0093e5ad36958f98886cc2d74014 |