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',
        },
        {
            '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.

    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.

Demo

Known Issues

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

Changes

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.