sphinx-contrib / sphinx-contrib/openapi

Schema examples dont show

Open
#152 2 comments 1 reaction 0 assignees View on GitHub

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 example property has been deprecated in favor of the JSON Schema examples keyword. Use of example is 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:

Screenshot from 2024-03-22 17-40-01
Screenshot from 2024-03-22 17-39-55

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.