sphinx-contrib / openapi

OpenAPI (fka Swagger) spec renderer for Sphinx.
https://sphinxcontrib-openapi.readthedocs.io
BSD 2-Clause "Simplified" License
110 stars 80 forks source link

Schema examples dont show #152

Open AngryUbuntuNerd opened 7 months ago

AngryUbuntuNerd commented 7 months ago

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.

stephenfin commented 7 months ago

Yeah we don't support examples at the moment. Those would need to be added.

AngryUbuntuNerd commented 7 months ago

Happy to put together a PR for adding the support. Would just need a few pointers where to make the changes.