feat: support schema.examples array in example generator (#1270)

Adds support for the OpenAPI 3.1 / JSON Schema 'examples' array in the
schema example generator (createSchemaExample.ts):

- Check schema.examples after schema.example in sampleFromSchema
- Check property.examples after property.example in sampleFromProp
- Uses first example from array when examples is non-empty
- Guards against empty arrays to prevent fallback issues

Closes #1219

Co-authored-by: Jens Claes <[email protected]>

Author: sserrata

packages/docusaurus-plugin-openapi-docs/src/openapi/createSchemaExample.ts

@@ -91,7 +91,12 @@ function sampleFromProp(
 
   // TODO: handle discriminators
 
-  if (prop.oneOf) {
+  // Check for explicit example/examples first (OAS 3.1 support)
+  if (prop.example !== undefined) {
+    obj[name] = prop.example;
+  } else if (prop.examples !== undefined && prop.examples.length > 0) {
+    obj[name] = prop.examples[0];
+  } else if (prop.oneOf) {
     obj[name] = sampleFromSchema(prop.oneOf[0], context);
   } else if (prop.anyOf) {
     obj[name] = sampleFromSchema(prop.anyOf[0], context);
@@ -114,6 +119,7 @@ export const sampleFromSchema = (
     let {
       type,
       example,
+      examples,
       allOf,
       properties,
       items,
@@ -126,6 +132,11 @@ export const sampleFromSchema = (
       return example;
     }
 
+    // OAS 3.1 / JSON Schema: examples is an array
+    if (examples !== undefined && examples.length > 0) {
+      return examples[0];
+    }
+
     if (oneOf) {
       if (properties) {
         const combinedSchemas = merge(schemaCopy, oneOf[0]);