Hi!

I used OpenAPI 3.0.1,

I have a warning for parametres with type "integer", "string" and etc:

No "type" specified at "/paths/~1test/post/parameters/0". Automatically detected: "object"

For examle:

- name: projectId in: query required: true schema: type: integer format: int64

Apparently, sphinx-build fails to build some targets (e.g. text, latexpdf, XML) with this extension included.
An IOError Exception is thrown.

IOError: [Errno 2] No such file or directory: u'/mnt/g/git/api-docs/build/text/_static/redoc.js'

This appears to happen because redoc.py is unable to copy the redoc.js to the target folder for some reason.

Build target in the traceback: text

The full traceback:
sphinx-err-Zm6iYM.log

Redoc just released version 2 alpha with support for OpenAPI 3, is there any plan to support the newest Redoc? :-)

Attempting to render an OpenAPI 3.0 specification partially works but is missing attributes like "server" which replaced "host" and "requestBody" which replaced "parameters.body" in the upgrade from swagger 2.0 to OpenAPI 3.0

since [email protected] there is support for opeapi: 3.0.1

So far ReDoc has the following options:

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

It would be nice to have a way to propagate them from Sphinx's conf.py to ReDoc page as one may be eager to have them in some cases.

Hello I have the following error when I do "make html" in my doc directory

TypeError('sequence item 0: expected str instance, int found',)

If I do the following change in my conf.py it remove the error, it is normal ?

            'expand-responses': [ 200, 201 ],

            'expand-responses': [ "200", "201" ],

Cheers.

It would be nice to be able to provide URL for the reddoc.js to be used.
Plugin could use it to download script and put it instead of bundled reddoc.js into the _static.

It would give a possibility to update reddoc without updating this extension. (for example OpenAPI 3.0 supported only in RedDoc 2.x) and ATM some tricks are needed to be able to use this extension to render it.

If Sphinx fails to build docs there's a chance that sphinxcontrib-redoc fails to copy redoc.js to {outdir}/_static. The reason is that it unconditionally tries to copy redoc.js when build is finished (successfully or unsuccessfully) without ensuring that {outdir}/_static exists.

Here's the traceback example:

Traceback (most recent call last):
  File "/Users/ikalnytskyi/devel/xsnippet-api/.tox/docs/lib/python3.6/site-packages/sphinx/cmdline.py", line 296, in main
    app.build(opts.force_all, filenames)
  File "/Users/ikalnytskyi/devel/xsnippet-api/.tox/docs/lib/python3.6/site-packages/sphinx/application.py", line 348, in build
    self.emit('build-finished', err)
  File "/Users/ikalnytskyi/devel/xsnippet-api/.tox/docs/lib/python3.6/site-packages/sphinx/application.py", line 589, in emit
    results.append(callback(self, *args))
  File "/Users/ikalnytskyi/devel/xsnippet-api/.tox/docs/lib/python3.6/site-packages/sphinxcontrib/redoc.py", line 61, in assets
    os.path.join(app.builder.outdir, '_static', 'redoc.js'))
  File "/Users/ikalnytskyi/devel/xsnippet-api/.tox/docs/lib/python3.6/site-packages/sphinx/util/osutil.py", line 150, in copyfile
    shutil.copyfile(source, dest)
  File "/Users/ikalnytskyi/devel/xsnippet-api/.tox/docs/lib/python3.6/shutil.py", line 121, in copyfile
    with open(dst, 'wb') as fdst:
FileNotFoundError: [Errno 2] No such file or directory: '/Users/ikalnytskyi/devel/xsnippet-api/docs/_build/_static/redoc.js'

Example from https://sphinxcontrib-redoc.readthedocs.io/en/stable/:

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"], } }, ]

ReDoc doesn't have options "lazy", but it has "lazy-rendering". Another opts is written with error too.

My (local) yml spec file references to another (local) yml in the definition. However, the extension seems not able to detect the reference and copy them.
For example:

a.yml

# ...
components:
  schemas:
    user:
      $ref: 'b.yml#/components/schemas/user'
# ...

b.yml

# ...
components:
  schemas:
    user:
      type: object
# ...

and in conf.py

# ...
redoc = [
    {
        "name": "My API",
        "page": "path/to/a",
        "spec": "path/to/a.yml",
    },
]
# ...

The extension detects "path/to/a.yml" and copy it to _build/html/_spec. However, b.yml is not copied and the page just failed to load.

Could there be a way to list the yml files I want to use for rendering the docs page, and the extension will copy and prepare them (and manipulate the paths) for me?

Hi and first of all: thanks for this amazing project!

I was wondering if there could be an option for downloading the API spec in YAML too. The download button retrieves only a JSON version.

My use case is that we as an organisation actually works with the YAML versions as they are easier on the eyes and easier for non-tech people to look at and/or edit.

I don't see how I can integrate the generated api.html into my documentation. It's just there in the documentation folder and I cannot even link to it unless I use absolute links, right? So what does this extension actually do related to Sphinx? It would be great if I could link to it from a toctree.

Hi! Thank you for this extension!

I need to possibly specify in conf.py multiple yaml files for different languages.

On mentioning the below URL in conf.py, I get an extension error.

redoc_uri = 'https://unpkg.com/[email protected]/bundles/redoc.standalone.js'

Error:

Extension error (sphinxcontrib.redoc):
Handler <function assets at 0x7f76cf766310> for event 'build-finished' threw an exception (exception: <urlopen error [Errno -3] Temporary failure in name resolution>)

If you want an embedded openapi in the page, the order of the endpoints is not kept.
The issue stem from there : https://github.com/sphinx-contrib/redoc/blob/master/sphinxcontrib/redoc.py#L94

The yaml library does not keep the order of the keys in dict structure.

I 've made a test with oyaml (https://github.com/wimglenn/oyaml), in this case the order is kept.

As with sphinx-contrib/openapi#23, this could be beneficial to the long term visibility/sustainability of the project. Let me know if you agree/disagree or have any questions!

Very small issue.

Here's the screenshot of the docs

There is no semicolon here. But In the source It is present. I wonder how it's missing here.

Unable to render the page when used in more than one place and without a directive.

I have defined like:

redoc = [
    {
        'name': 'File Upload APIs',
        'page': 'spec/file_upload_apis',
        'spec': 'yaml_spec/openapi.yaml',
        'embed': True,
    }
]

1. The spec/file_upload_apis.rst is the placeholder file where I want the Redoc API documentation to be rendered.
2. The hyperlink to the above page looks like:

spec/pa_amr_apis.rst

.. toctree::
   :maxdepth: 5       

   file_upload_apis      //This works when used in toctree directive


file_upload_apis        // This does not work anywhere outside toctree directive

Should I have to use file_upload_apis only within some directive? And not on any page were I want ?

Hello

I see that I have examples in my openapi.yaml (https://gitlab.fusiondirectory.org/fusiondirectory/fd-plugins/raw/1.4-dev/webservice/html/openapi.yaml) but nothing is shown in the generated documentation.

I also set in my conf.py the following opts

'expand-responses': [ "200", "201" ],

Cheers.

I'm trying to use a relative URL to the spec.yaml file, which fails because it's interpreted as a file path:

Traceback (most recent call last):
  File "/usr/lib/python3.6/site-packages/sphinx/cmdline.py", line 304, in main
    app.build(args.force_all, filenames)
  File "/usr/lib/python3.6/site-packages/sphinx/application.py", line 331, in build
    self.builder.build_update()
  File "/usr/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 338, in build_update
    'out of date' % len(to_build))
  File "/usr/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 402, in build
    self.finish()
  File "/usr/lib/python3.6/site-packages/sphinx/builders/html.py", line 621, in finish
    self.finish_tasks.add_task(self.gen_additional_pages)
  File "/usr/lib/python3.6/site-packages/sphinx/util/parallel.py", line 50, in add_task
    res = task_func()
  File "/usr/lib/python3.6/site-packages/sphinx/builders/html.py", line 648, in gen_additional_pages
    for pagename, context, template in pagelist:
  File "/usr/lib/python3.6/site-packages/sphinxcontrib/redoc.py", line 47, in render
    os.path.join(specpath, specname))
  File "/usr/lib/python3.6/site-packages/sphinx/util/osutil.py", line 165, in copyfile
    if not path.exists(dest) or not filecmp.cmp(source, dest):
  File "/usr/lib/python3.6/filecmp.py", line 51, in cmp
    s1 = _sig(os.stat(f1))
FileNotFoundError: [Errno 2] No such file or directory: '/api/rest/spec.yaml'

I need to use a relative path because the generated docs will be deployed on multiple hosts, and I don't want to bind the spec to a specific host. As a workaround I'm using the full URL in the config, then edit the generated html file manually before deployment.

the proof for me just shows an endless "Loading"...

Is there a way to externalize the redoc config?
I'm trying not to utilize conf.py and using redoc.py to have the entries for yaml files.
redoc.py is available in /services...

Below is the entry in conf.py and it doesn't seem to be generating any html.

Any ideas?

conf.py

import os
import sys

sys.path.insert(0, os.path.abspath('./services'))

redoc.py located at /services

redoc = [
    {
        'name': 'User API',
        'page': 'userapi',
        'spec': 'userapispec.yml'
    }
]

Hello,

After running "make html" if I look at the documentation I have the next server URL

http://demo-custom.fusiondirectory.org/login

But normally it must be "http://demo-custom.fusiondirectory.org/fusiondirectory/rest.php/login".
From where come the server url ?

Cheers.