sphinx-contrib / sphinx-contrib/openapi
Schema examples dont show
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 126
- Forks
- 88
- PR merge metrics
- No merged PRs in 30d
Description
I have the given openapi.json which is generated using fastapi (I chopped it down to the relevant parts).
The relevant snippet is this one:
{
"components": {
"schemas": {
"Schedule": {
"examples": [
{
"schedule_id": "111111l901",
"task": "ping"
}
]
},
"ScheduleRequest": {
"examples": [
{
"task": "ping"
}
]
}
}
}
}
This is following the OpenAPI standard 3.1.0 which claims:
The
exampleproperty has been deprecated in favor of the JSON Schemaexampleskeyword. Use ofexampleis discouraged, and later versions of this specification may remove it.
Now I have added it to my docs using this block
.. openapi:: ./openapi.json
:examples:
But the generated examples are not using the examples from the document:
Notice that it says "string" instead of "111111l901" and "ping" as in the examples. It works better, but still not fully, when using example instead.
I can not figure out how to fix this in the code, so was wondering if someone can help.
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 with the supplied openapi.json and the .. openapi:: ./openapi.json directive using :examples:. Trace how schema examples are read and rendered, comparing them with the deprecated example behavior. Done means the generated documentation displays the values from the examples arrays instead of placeholder strings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- fastapi, openapi, python
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100