fix(openapi): serialize Reference objects with $ref in the generated document

[soyuka]

Summary

A custom OpenApiFactory placing a Reference object in Operation::$responses produced "ref" instead of "$ref" in the generated OpenAPI document. The dedicated inline ObjectNormalizer used by OpenApiNormalizer was constructed without a class metadata factory or a metadata-aware name converter, so Reference::getRef()'s #[SerializedName('$ref')] was never applied. Reference::$ref is the only #[SerializedName] among the OpenAPI models, so the change only affects this property — emitting the spec-correct $ref.

Reproduction

Serializing an OpenAPI document whose components/responses reference a schema via a Reference object emitted the key as ref, which is invalid per the OpenAPI spec.

Test plan

• Added failing unit test (OpenApiNormalizerTest) and functional test (OpenApiTest, real DI) asserting $ref is present.
• Both pass after the fix.
• Existing OpenAPI normalizer/serializer suites stay green (27 tests, 259 assertions).

Note: a pre-existing, unrelated failure in OpenApiFactoryTest::testInvoke (a 422 response description default) exists on 4.3 HEAD independently of this change.

Fixes #8143

[thomas-hiron]

Hi! I think there is a regression with this.
My config is the following:

framework:
    serializer:
        name_converter: serializer.name_converter.camel_case_to_snake_case

api_platform:
    path_segment_name_generator: api_platform.metadata.path_segment_name_generator.dash
    name_converter: serializer.name_converter.camel_case_to_snake_case

And now, the spec is generated in snake_case: operation_id, extension_properties...
And openapi-generator-cli doesn't support extension_properties:

-attribute paths.'/api/article'(get).extension_properties is unexpected

How to configure the spec being generated in camel case? Should I open an issue?

Thanks!

[soyuka]

@thomas-hiron confirmed, this is a regression — not a config issue on your side. #8306 wired serializer.name_converter.metadata_aware into the OpenAPI serializer to honor #[SerializedName('$ref')], but that service carries your framework.serializer.name_converter as its fallback, so the global camelCase_to_snake_case converter leaked into the whole document (operation_id, extension_properties, …).

Fix in #8360: a dedicated MetadataAwareNameConverter with no fallback — $ref is still honored, the global converter no longer applies. No config change needed on your end.