Cannot create a "RequestBody" attribute with a valid mapping between "schema" and "examples"

[DavidGarciaCat]

Good day,

I am trying to generate an auto-mapping between the "oneOf" of the Schema and the "examples".

Although, initially, it might seem like a bug/issue to report to the Swagger PHP library, I have the feeling this case needs to be reported here because I get the issue when trying to use the Nelmio\Model class:

    #[OA\RequestBody(
        description: '...',
        content: new OA\MediaType(
            mediaType: 'application/json',
            schema: new OA\Schema(oneOf: [
                new OA\Schema( ref: new Nelmio\Model(type: PayPalType::class) ),
                new OA\Schema( ref: new Nelmio\Model(type: StripeType::class) ),
            ]),
            examples: [
                PayPalType::DISCRIMINATOR_TYPE => new OA\Examples(
                    example: PayPalType::DISCRIMINATOR_TYPE,
                    summary: 'PayPal',
                    description: "...",
                    value: '{"property": "string"}', // this works
                ),
                StripeType::DISCRIMINATOR_TYPE => new OA\Examples(
                    example: StripeType::DISCRIMINATOR_TYPE,
                    summary: 'Stripe',
                    description: "...",
                    ref: new Nelmio\Model(type: StripeType::class), // this fails
                ),
            ],
        )
    )]

The ref parameter seems to expect a string (targeting the Model), but it seems to generate an error using the same approach, using the Nelmio Model.

I have tried to use the example property as part of the oneOf Schema/Model definition, but it didn't work either:

    #[OA\RequestBody(
        description: '...',
        content: new OA\MediaType(
            mediaType: 'application/json',
            schema: new OA\Schema(oneOf: [
                new OA\Schema(
                    ref: new Nelmio\Model(type: PayPalType::class),
                    example: new Nelmio\Model(type: PayPalType::class),
                ),
            ]),
        )
    )]

Any suggestions or ideas to keep using the Nelmio Model?

I have been able to create examples by setting the value key as an array or a string. Still, it means any change in my Type objects is not automatically updated and rendered in the documentation page, doubling the number of updates and leading to potentially broken documentation in case I missed updating the controller.

[DavidGarciaCat]

This case might be related to https://github.com/nelmio/NelmioApiDocBundle/issues/1811 but, as I was saying, I believe the problem is caused by the usage of the Nelmio\Model class and how it is processed when rendering the documentation.

Maybe a __toString() magic method is missing?