[Bug]: describing custom header parameter leads to schema error

[HEKET313]

Version

5.9.5

Description

Swagger-php version: 5.8.3

I add a header parameter to components via describer in my bundle to later add it to every single route of a service where this bundle is used.

Here's describer code:

use Nelmio\ApiDocBundle\Describer\DescriberInterface;
use OpenApi\Annotations\OpenApi;
use OpenApi\Attributes as OA;

class HeadersDescriber implements DescriberInterface
{
    public function describe(OpenApi $api): void
    {
        $api->merge([new OA\Parameter(
            name: 'X-API-Version',
            description: 'The version of the API to use',
            in: 'header',
            required: true,
            schema: new OA\Schema(
                type: 'string',
            ),
            example: '1.0.0'
        )]);
    }
}

And then I add it to every endpoint like that:

$operation->merge([
    new HeaderParameter(
        ref: '#/components/parameters/X-API-Version',
    ),
]);

As a result I get the following error:

User Warning: @OA\Schema() is missing key-field: "schema" in 

This error is not raised if schema definition is extended with additional schema property inside schema:

$api->merge([new OA\Parameter(
    name: 'X-API-Version',
    description: 'The version of the API to use',
    in: 'header',
    required: true,
    schema: new OA\Schema(
        schema: 'Some schema', // absence raises the error above
        type: 'string'
    ),
    example: '1.0.0'
)]);

but that leads to invalid OpenAPI component parameter definition:

components:
  parameters:
    X-API-Version:
      name: X-API-Version
      in: header
      description: 'The version of the API to use'
      required: true
      schema:
        schema: SomeSchema // invalid attribute
        type: string
      example: 1.0.0

I found out that for some reason Schema from the very first example is merged into components.schemas in pipeline, but if I just comment the line with error in AbstractAnnotation.php the result openapi.yaml file is generated correctly without this schema under the schemas.

JSON OpenApi

Can not provide full openapi

Additional context

No response

[HEKET313]

Gemini has proposed a workaround which works but looks ugly

$schema = new OA\Schema(type: 'string');
$parameter = new OA\Parameter(
    parameter: 'X-API-Version',
    name: 'X-API-Version',
    description: 'The version of the API to use',
    in: 'header',
    required: true,
    schema: $schema,
    example: '1.0.0'
);
$schema->_context = new \OpenApi\Context(['nested' => $parameter], $parameter->_context);

$api->merge([$parameter]);