sphinx-contrib / sphinx-contrib/openapi
Unable to render examples with only readonly properties
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 126
- Forks
- 88
- PR merge metrics
- No merged PRs in 30d
Description
When using the old renderer (since I cannot use the new one due to #124 and I want to keep API docs splitted based on path) with OpenAPI 3.1 and examples enabled there is a problem due to how examples are rendered and guessed:
If no example is provided in the swagger file one is guessed from _parse_schema, but if there are only readonly properties this method returns an object (_READONLY_PROPERTY) which is not serializable. This results in an unhandled exception (TypeError: Object of type object is not JSON serializable) which is not what is intended.
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/openapi31.py at lines 214-236 and follow _parse_schema, especially the _READONLY_PROPERTY result. Reproduce with an OpenAPI 3.1 schema containing only readonly properties and examples enabled; done means the old renderer no longer raises a JSON serialization TypeError when guessing an example.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100