Incompatiable with OpenApi 3.0.1

[kulsingh0]

Brief Introduction:
We are facing issues while generating the sphinx documentation while using openAPI 3.0.1 yml template files .
But it works successful with the Swagger 2.0 template.

Ask:
Can you please confirm if sphinx supports OpenAPI 3.01 templates for documentation?

Problem Statement :
Specifically, we are facing issues for following parameters in documentation.
a) Request Json Parameters
b) Response Json Parameters

As per below example of Open API 3.01 template it expects

( schema property is child of content)

where as in Swagger 2.0 the structure looks like this.

if we use the Swagger 2.0 yml to generate the HTML documentation then I successfully generates the Request JSON Parameter and Response JSON Parameters as below.

where as with former with openAPI 3.0.1 template it failed to load these request Json parameter and response Json Parameters

You can refer any sample open API 3.0.1 template from internet to reproduce this issue.

Really appreciate your prompt support.

[kulsingh0]

Any update please?

[igo95862]

@kulsingh0 Try switching to new renderer on latest version. Add openapi_default_renderer='httpdomain' to conf.py

[rokroskar]

@igo95862 that doesn't seem to solve the problem for me:

Sphinx==3.4.3
sphinxcontrib-httpdomain==1.7.0
sphinxcontrib-openapi==0.7.0

It also doesn't work on the test API spec: https://github.com/sphinx-contrib/openapi/blob/master/tests/testspecs/v3.0/petstore-expanded.yaml

Yields:

[rabernat]

I recently discovered this issue (xref pangeo-forge/pangeo-forge-orchestrator#28). In that project, we are trying to include API documentation from a fastapi api object directly in a sphinx website. I imagine this is a very common scenario for python devs in 2022. We accomplish this with the following simple code in conf.py.

import yaml
from pangeo_forge_orchestrator.api import api  # created by FastAPI()

api_spec = api.openapi()  # openapi-style dictionary 
with open("openapi.yaml", mode='w') as fp:
    yaml.dump(api_spec, fp)

Plus the following RST in our sphinx site

.. openapi:: openapi.yaml

Fastapi exports openapi 3.0.x style metadata. The bug described here means that response and request JSON are not rendered. (See example site.)

We see two possible options to resolve the problem:

• Implement a manual translation step, wherein we reformat api_spec to use the swagger-style nesting of response objects
• Help resolve this problem upstream, i.e. in sphinxcontrib.openapi

Would the maintainers be willing to sketch out a roadmap of what it would take to fix this bug? We may be able to allocate developer time to such an effort if the path is clear.

[aleksandergabriel]

I just noticed the same problem.
Sphinx==4.5.0
sphinxcontrib-httpdomain==1.8.0
sphinxcontrib-openapi==0.7.0

Adding openapi_default_renderer='httpdomain' to conf.py, also did not solve the problem for me.

Is there a timeline when solution can be expected?

[david-i-berry]

This issue appears to be related to the resolution of references in the schemas.

The line

openapi/sphinxcontrib/openapi/renderers/_httpdomain_old.py

Line 42 in ee9e232

utils.normalize_spec(spec, **self._options)

Appears to be missing from the new renderer. Inserting this line at

openapi/sphinxcontrib/openapi/renderers/_httpdomain.py

Line 236 in ee9e232

and updating the includes (plus openapi_default_renderer='httpdomain') resolves the issue for me.

[david-i-berry]

I've made a fork with the update applied at:

https://github.com/david-i-berry/sphinxcontrib-openapi

I've only tested with my use case but it renders as expected (i.e. with the request and response objects now shown).

[amhest]

I just hit this issue with $ref in the responses on openapi 3.0.1. The fix from @david-i-berry on July 4, 2023 worked perfectly for me with both HTML and PDF. Any chance we can get this into a build?