Schemas are assumed to be objects, not type combinators

[arrdem]

https://github.com/sphinx-contrib/openapi/blob/547f6453753b9d7accb30fa8d1eee2b8e02ebc0d/sphinxcontrib/openapi/openapi30.py#L260

This line assumes that every schema it operates on will be {type: string}, {type: object} or soforth, and fails to support the type combinators anyOf, oneOf and allOf when they occur at the top level. While I appreciate that providing a meaningful rendering of such types is challenging, it'd be awesome if the openapi plugin could at least fail gracefully and let a user know what killed it.

  File "sphinxcontrib/openapi/openapi30.py", line 262, in _httpresource
    type=param['schema']['type'],
KeyError: 'type'

isn't a great UX and hunting down what part of my spec was killing Sphinx took a hot second.

[ikalnytskyi]

Hey @arrdem,

Thanks for reporting this issue. Can you please try to render your spec using an experimental renderer?

.. openapi:httpdomain:: path/to/your/spec

It's not yet feature compatible with the old one, but I'm working on addressing this issue. You can find all supported directive parameters of this new renderer here

https://github.com/sphinx-contrib/openapi/blob/6cd85b92ca243eaf6fc8d353efb7eb9daf6bc717/sphinxcontrib/openapi/renderers/_httpdomain.py#L116-L125

[falkben]

Thanks, had a similar issue and using the new renderer fixed it.

Some additional information:

We are using this extension to generate Sphinx documentation on our FastAPI endpoints (after generating the openapi schema from fastapi). When query params have an Enum type annotation, they get the anyOf schema, as reported by the original poster. Specifying the httpdomain renderer seems to skip over this entry, which is fine for us.

[ikalnytskyi]

Thanks for the feedback, @falkben. I don't have much time to work on this but I'll try to release a new version in a week or two, where new renderer will be default one. It should fix a lot of bugs.

[ibiris]

Thanks for this update, I am facing the same issue also.

Is this release going to happen some time soon? Just checking what is the timeline for this, as the last comment is from 2+ months ago.