OpenApiSchema plural examples are not serialized for OpenAPI 2.0/3.0

[baywet]

Summary

OpenApiSchema.Examples currently serializes only for OpenAPI 3.1+ as the JSON Schema examples keyword. For OpenAPI 2.0 and 3.0, plural schema examples are omitted instead of being preserved as a JSON Schema compatibility extension.

Expected behavior

Schema-level example fields should serialize as follows:

• example singular serializes as example for OpenAPI 2.0, 3.0, and 3.1+.
• examples plural serializes as examples for OpenAPI 3.1+.
• examples plural serializes as x-jsonschema-examples for OpenAPI 2.0 and 3.0.

Current behavior

• example singular is serialized as example in all versions.
• examples plural is written from OpenApiSchema.WriteJsonSchemaKeywords, which is only called for OpenAPI 3.1+.
• The OpenAPI 3.0 JSON Schema compatibility path writes other x-jsonschema-* keywords, but does not write Examples.
• The OpenAPI 2.0 schema serialization path also does not write Examples.

Notes

The existing x-examples constant/behavior appears to apply to parameter/response example maps, not schema-level JSON Schema examples. Schema-level plural examples should use x-jsonschema-examples when down-converting to OpenAPI 2.0 or 3.0.

[Youssef1313]

@baywet The file I commented on in dotnet/aspnetcore#67894 was a snapshot test for 3.0, which was surprising me. Do we know how we can end up serializing Examples in 3.0? Nothing in the current existing code that I can see do that.

[baywet]

@yousef1313 this is confusing to me as well.

Example is serialized in all cases here but examples is only serialized here, which only gets called when the version is or above 3.1