Example values for individual request body fields are not compliant with OpenAPI specification

[shfrmn]

Prerequisites

• [X] I have written a descriptive issue title
• [X] I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.24.3

Plugin version

8.12.1

Node.js version

21.3.0

Operating system

macOS

Operating system version (i.e. 20.04, 11.3, 10)

Sonoma 14.1.1

Description

Fastify requires examples field to be an array of values, which are subsequently transformed into valid OpenAPI format.

schemaToMedia is the function that performs this transformation

1. If array contains one element, examples property is deleted and replaced with example containing a single value
2. If array contains multiple elements, it's remapped to an object according to the standard

Everything works well in URL params, query params and other schemas that cannot be recursively nested, but when it comes to the request body, transformation is only performed at the top level of the schema. Examples for each individual field are not transformed at all and stay in the original array form, which is in fact not compliant with the OpenAPI standard.

The impact of this issue is that it breaks various related tooling. Two downstream issues that I encountered were:

• Scalar swagger editor currently cannot interpolate examples in request body
• orval fails schema validation

Example endpoint:

fastify.post(
  "/",
  {
    schema: {
      summary: "Test",
      body: {
        type: "object",
        properties: {
          text: {
            examples: ["Lorem ipsum"],
            type: "string",
          },
        },
        required: ["text"],
      },
    },
  },
  handler
)

Output:

{
  "openapi": "3.0.3",
  "info": {},
  "paths": {
    "/": {
      "post": {
        "summary": "Test",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "examples": [
                      "Lorem ipsum"
                    ],
                    // ^^^ SHOULD NOT BE AN ARRAY
                    "type": "string"
                  }
                },
                "required": [
                  "text"
                ]
              }
            }
          },
          "required": true
        }
      }
    }
  },
  "servers": []
}

Steps to Reproduce

1. Configure fastify-swagger in openapi mode
2. Add examples to individual fields of a request body like in the example above
3. Bingo (check the output json)

Expected Behavior

Current implementation of schemaToMedia is sufficient, however it should be called recursively for each of the properties in the request body.

[Uzlopak]

@shfrmn

Are willing to provide a PR :)?

[shfrmn]

Sure, if there are no objections. Please let me know what you think.

[mcollina]

A PR would be lovely.

[shfrmn]

Feel free to review and comment — @mcollina, @Uzlopak