sphinxcontrib-redoc

Hint

Check out sphinxcontrib-openapi if you are interested in rendering OpenAPI spec within Sphinx page (i.e. inline).

_images/logo.png

The Sphinx extension that renders OpenAPI (fka Swagger) specs with love (❤️) using amazing ReDoc. Don’t believe it? Here’s the proof. Now stop frustrating and start moving your projects to OpenAPI and ReDoc with this small first step:

$ pip install sphinxcontrib-redoc

Usage

The whole configuration is done via Sphinx’s conf.py. All you have to do is to:

  • enable this extension

    extensions = [
       # ...
       'sphinxcontrib.redoc',
    ]
    
  • define OpenAPI specs to render

    redoc = [
        {
            'name': 'Batcomputer API',
            'page': 'api',
            'spec': 'specs/batcomputer.yml',
            'embed': True,
        },
        {
            'name': 'Example API',
            'page': 'example/index',
            'spec': 'http://example.com/openapi.yml',
            'opts' {
                'lazy': False,
                'nowarnings': False,
                'nohostname': False,
                'required-props-first': True,
                'expand-responses': [200, 201],
            }
        },
    ]
    

    where

    name

    An API (human readable) name that will be used as page title.

    page

    A page name to be used to form an output file. Passing api means: save rendered page as {outdir}/api.html. It also support complex paths such as foo/bar/api which will be resolved into something like {outdir}/foo/bar/api.html.

    spec

    A path to an OpenAPI spec to be rendered. Can be either an HTTP(s) link to external source, or filesystem path relative to conf directory.

    embed (default: False)

    If True, the spec will be embedded into the rendered HTML page. Useful for cases when a browsable API ready to be used without any web server is needed. The spec must be an UTF-8 encoded JSON on YAML OpenAPI spec; embedding an external spec is currently not supported.

    opts

    An optional dictionary with some of ReDoc settings that might be useful. Here they are

    lazy-rendering (default: False)

    If set, enables lazy rendering mode which is useful for APIs with big number of operations (e.g. > 50). In this mode ReDoc shows initial screen ASAP and then renders the rest operations asynchronously while showing progress bar on the top.

    suppress-warnings (default: False)

    If set, no warnings are rendered at the top of the document.

    hide-hostname (default: False)

    If set, both protocol ans hostname are not shown in the operational definition.

    required-props-first (default: False)

    If set, ReDoc shows required properties first in the same order as in required array. Please note, it may be slow.

    expand-responses (default: [])

    A list of response codes to be expanded by default.

    hide-loading (default: False)

    Do not show loading animation. Useful for small OpenAPI specs.

    native-scrollbars (default: False)

    Use native scrollbar for sidemenu instead of perfect-scroll. May dramatically improve performance on big OpenAPI specs.

    untrusted-spec (default: False)

    If set, the spec is considered untrusted and all HTML/markdown is sanitized to prevent XSS.

  • if you are not ok with default version, specify the one you want to use

    redoc_uri = 'https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js'
    

Demo

Known Issues

  • ReDoc has some performance issues, so loading a pretty huge OpenAPI spec may take a time.

Changes

1.5.1 (2018-08-05)

  • Fix critical issue when relative path to an OpenAPI spec didn’t work.

    [#17]

1.5.0 (2018-07-28)

  • New embed option. When True, the spec will be embedded into the rendered HTML page. Thanks @etene.

    [PR #14]

  • Add redoc_uri Sphinx option to override default redoc.js.

    [#13, PR #16]

1.4.0 (2018-03-24)

  • Update redoc.js to 1.21.2. [PR #10]

  • Add support for the following ReDoc options:

    • hide-loading
    • native-scrollbars
    • untrusted-spec

    [PR #10]

1.3.0 (2017-05-12)

  • Update redoc.js to 1.16.0. [PR #8]

1.2.0 (2017-04-24)

  • Update redoc.js to 1.14.0. [PR #6]

  • Add support for the following ReDoc options:

    • no-auto-auth
    • path-in-middle-panel

    [PR #7]

1.1.0 (2017-04-12)

  • Add support for the following ReDoc options:

    • lazy-rendering
    • suppress-warnings
    • hide-hostname
    • required-props-first
    • expand-responses

    [#4, PR #5]

1.0.1 (2017-04-10)

  • Do not copy assets (i.e. redoc.js) to output directory if Sphinx build was finished with errors. [#1]

1.0.0 (2017-04-08)

  • First public release.