Bug: The `examples` keyword from OpenAPI 3.1.0 is ignored in some places

[jceipek]

In OpenAPI 3.1.0, the example schema keyword is deprecated in favor of the examples keyword from JSON Schema. RapiDoc ignores the examples keyword in some contexts, which causes it to omit schema-provided examples from its output entirely in some cases, unless they are provided via the deprecated keyword.

NOTE: I've created a PR to address this problem here: https://github.com/rapi-doc/RapiDoc/pull/1065

Reproduction and Impact

1. Open openapi-spec-minimal.json (included at the end of this issue) via the "LOCAL JSON FILE" button at https://rapidocweb.com/examples/example1.html
2. Expand POST /api/test
3. Look at the EXAMPLE in the RESPONSE section

Actual behavior:

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

Note [ "string" ] under list_field.

Expected behavior:

{
  "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. Note that this expected behavior is also present when using https://editor-next.swagger.io/

Minimal Schema

openapi-spec-minimal.json:

{
  "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"
                }
              }
            }
          }
        }
      }
    }
  }
}

Note that this schema validates using https://editor-next.swagger.io/, but the example field is shown as deprecated, as expected.

[mrin9]

thanks i will take a look soon. Can you tell me how does it work when you provide multiple examples ? the spec contains only one example in the examples array. When there are multiple , it should be able to show them all

[jceipek]

@mrin9

thanks i will take a look soon.

Thanks! I just got back from a winter break, myself.

Can you tell me how does it work when you provide multiple examples ? the spec contains only one example in the examples array. When there are multiple , it should be able to show them all

It would be nice to support multiple examples. However, neither SwaggerEditor nor RapiDoc (even with https://github.com/rapi-doc/RapiDoc/pull/1065) supports multiple examples.

The minimal spec I provided above includes:

"string_field": {
  "description": "String Field",
  "examples": ["Included in output", "Missing from output since only one example is displayed"],
  "type": "string"
}

Note the second element of the array there. Prior to https://github.com/rapi-doc/RapiDoc/pull/1065, RapiDoc and SwaggerEditor both display "Included in output" but not "Missing from output since only one example is displayed".

https://github.com/rapi-doc/RapiDoc/pull/1065 only addresses the problem that the "examples" array is ignored entirely in some situations (as with "list_field" in the spec above). It does not add any new support for displaying multiple examples.

I have noticed that RapiDoc sometimes displays multiple examples, but only in situations with anyOf.