sphinx-contrib / sphinx-contrib/openapi
Exception raised on enum query parameters without "type"
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 126
- Forks
- 88
- PR merge metrics
- No merged PRs in 30d
Description
JSON Schema does not require "type" to be present for enums, see also https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values.
The plugin however requires it for all query parameter schemas:
https://github.com/sphinx-contrib/openapi/blob/4f78db9c8ca2cefc4e4c1eeb46552a8d9d432855/sphinxcontrib/openapi/openapi30.py#L279-L282
Sample error:
2021-01-12T14:38:38.9415027Z Exception occurred:
2021-01-12T14:38:38.9416063Z File "/__w/1/s/env/lib/python3.8/site-packages/sphinxcontrib/openapi/openapi30.py", line 281, in _httpresource
2021-01-12T14:38:38.9416591Z type=param['schema']['type'],
2021-01-12T14:38:38.9416959Z KeyError: 'type'
Sample parameter:
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"enum": [
"PENDING",
"TRUSTED",
"RETIRED"
]
}
}
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 at _httpresource, especially the query-parameter handling around the referenced lines. Reproduce the sample enum-only parameter and verify that documentation generation no longer raises KeyError when "type" is absent.
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
- Clearly specified
- Newbie friendliness
- 62/100