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.

    template

    Non default template to use to render ReDoc HTML page. Must be either passed, or omitted.

    Warning

    When custom template is used, settings such as name, embed or opts may not work if they are not supported by the template. Use custom templates with caution.

    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.6.0 (2020-04-17)

  • Add support for custom ReDoc templates. [PR #27]
  • Drop Python 3.4 support. [PR #34]
  • Fix issue when the extension may trigger build failure when other than html builders are used (e.g. linkcheck). [PR #32]

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.