sphinx-contrib / sphinx-contrib/openapi
Schemas are assumed to be objects, not type combinators
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 126
- Forks
- 88
- PR merge metrics
- No merged PRs in 30d
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in sphinxcontrib/openapi/openapi30.py around line 260, where _httpresource accesses param['schema']['type']; inspect how schema parameters are rendered. Reproduce the failure with a top-level anyOf, oneOf, or allOf schema, then verify that the plugin no longer raises KeyError and reports the problematic schema clearly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, python
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100