feat(api-explorer): add OpenAPI 3.1 schema.examples support (#1269)

Adds support for the OpenAPI 3.1 schema.examples array in the API Explorer
Body component. This is different from Media Type examples (which is an
object with named examples) - schema.examples is an array of example values
as per JSON Schema alignment in OAS 3.1.

- Handle schema.examples for JSON content types
- Handle schema.examples for XML content types
- Add test cases for schema.examples

Closes #1164 (alternative implementation)

Author: sserrata

demo/examples/tests/schemaExamples.yaml

@@ -0,0 +1,106 @@
+openapi: 3.1.0
+info:
+  title: Schema Examples API (OAS 3.1)
+  description: Demonstrates OpenAPI 3.1 schema.examples support.
+  version: 1.0.0
+tags:
+  - name: schemaExamples
+    description: OpenAPI 3.1 schema examples tests
+paths:
+  /schema-examples-array:
+    post:
+      tags:
+        - schemaExamples
+      summary: Schema with examples array (OAS 3.1)
+      description: |
+        OpenAPI 3.1 allows `examples` at the schema level as an array of values.
+        This is different from Media Type `examples` which is an object with named examples.
+
+        Schema:
+        ```yaml
+        schema:
+          type: object
+          properties:
+            name:
+              type: string
+            age:
+              type: integer
+          examples:
+            - name: "John Doe"
+              age: 30
+            - name: "Jane Smith"
+              age: 25
+        ```
+      requestBody:
+        description: Request body with schema.examples array
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+                age:
+                  type: integer
+              examples:
+                - name: "John Doe"
+                  age: 30
+                - name: "Jane Smith"
+                  age: 25
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                  message:
+                    type: string
+                examples:
+                  - id: 1
+                    message: "User created successfully"
+                  - id: 2
+                    message: "User updated successfully"
+
+  /schema-example-vs-examples:
+    post:
+      tags:
+        - schemaExamples
+      summary: Schema example vs examples comparison
+      description: |
+        Demonstrates the difference between:
+        - `schema.example` (singular) - used for generated example
+        - `schema.examples` (plural, OAS 3.1) - array of example values
+        - `content.example` (Media Type level)
+        - `content.examples` (Media Type level, named examples object)
+      requestBody:
+        description: Request with both schema.example and schema.examples
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                status:
+                  type: string
+                  enum:
+                    - active
+                    - inactive
+                    - pending
+                count:
+                  type: integer
+                  minimum: 0
+              examples:
+                - status: "active"
+                  count: 10
+                - status: "inactive"
+                  count: 0
+                - status: "pending"
+                  count: 5
+      responses:
+        "200":
+          description: Successful response

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Body/index.tsx

@@ -96,6 +96,8 @@ function Body({
   const schema = requestBodyMetadata?.content?.[contentType]?.schema;
   const example = requestBodyMetadata?.content?.[contentType]?.example;
   const examples = requestBodyMetadata?.content?.[contentType]?.examples;
+  // OpenAPI 3.1 / JSON Schema: schema.examples is an array of example values
+  const schemaExamples = schema?.examples as any[] | undefined;
 
   if (schema?.format === "binary") {
     return (
@@ -254,6 +256,17 @@ function Body({
         });
       }
     }
+    // OpenAPI 3.1: schema.examples is an array of example values
+    if (schemaExamples && Array.isArray(schemaExamples)) {
+      schemaExamples.forEach((schemaExample, index) => {
+        const body = JSON.stringify(schemaExample, null, 2);
+        examplesBodies.push({
+          label: `Example ${index + 1}`,
+          body,
+          summary: undefined,
+        });
+      });
+    }
     language = "json";
   }
 
@@ -299,6 +312,26 @@ function Body({
         });
       }
     }
+    // OpenAPI 3.1: schema.examples is an array of example values
+    if (schemaExamples && Array.isArray(schemaExamples)) {
+      schemaExamples.forEach((schemaExample, index) => {
+        let formattedXmlBody;
+        try {
+          formattedXmlBody = format(json2xml(schemaExample, ""), {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          });
+        } catch {
+          formattedXmlBody = json2xml(schemaExample);
+        }
+        examplesBodies.push({
+          label: `Example ${index + 1}`,
+          body: formattedXmlBody,
+          summary: undefined,
+        });
+      });
+    }
     language = "xml";
   }