Fix #1067: Add basic support for examples as well as example

[jceipek]

This PR fixes the following bug, #1067: the examples keyword is not supported at all in some contexts, which causes some response fields to be shown with a generic example even though a schema-supplied example is available.

In cases where it wasn't supported at all, we instead now pick the first example from examples, which is a valuable incremental improvement and matches the behavior of https://editor-next.swagger.io/.

Given the following minimal, valid spec:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Test API",
    "version": "0.0.1",
    "description": "Minimal test"
  },
  "paths": {
    "/api/test": {
      "post": {
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "list_field": {
                      "description": "List of Strings",
                      "examples": [["Bug: missing from output"]],
                      "items": { "type": "string" },
                      "type": "array"
                    },
                    "list_field_single_example": {
                      "description": "List of Strings single example",
                      "example": ["Deprecated but included in output"],
                      "items": { "type": "string" },
                      "type": "array"
                    },
                    "string_field": {
                      "description": "String Field",
                      "examples": ["Included in output", "Missing from output since only one example is displayed"],
                      "type": "string"
                    }
                  },
                  "required": [
                    "list_field",
                    "string_field"
                  ],
                  "title": "Demo",
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}

Before this PR, the example response was:

{
  "list_field": [
    "string"
  ],
  "list_field_single_example": [
    "Deprecated but included in output"
  ],
  "string_field": "Included in output"
}

Note [ "string" ] under list_field.

Now the example response is:

{
  "list_field": [
    "Bug: missing from output"
  ],
  "list_field_single_example": [
    "Deprecated but included in output"
  ],
  "string_field": "Included in output"
}

Note [ "Bug: missing from output" ] under list_field.

[jceipek]

@mrin9 Would you consider merging this as-is? It doesn't add any new support for displaying multiple examples, but it at least makes the behavior more consistent (examples was supported in some places but not others). SwaggerEditor also doesn't support multiple examples, but does support the examples keyword everywhere. See #1067 (comment)

[mrin9]

I have reviewed it and it has passed all our internal tests and also is a welcome change

So it will get merged as is. It might take a month or so as we are working on migrating to Vite based packaging and Astro based documentation .
You can use your branch for the time being as an temporary arrangement ...and be sure the feature will be available in our next release