Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Provides the swaggerui directive for reST files to build an interactive HTML page with your OpenAPI specification document.

Project description

https://travis-ci.org/sphinx-contrib/sphinxcontrib-swaggerui.svg?branch=master

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.

Note

  1. 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.
  2. You will probably need to edit the CSS styles using your own CSS files.

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;
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinxcontrib-swaggerui, version 0.0.10
Filename, size File type Python version Upload date Hashes
Filename, size sphinxcontrib-swaggerui-0.0.10.tar.gz (58.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page