@Schema field-level description ignored when using custom type with $ref #2723

[ramazangirgin]

I'm encountering an issue with Springdoc when using custom types in DTOs for generating OpenAPI documentation. Specifically, I have a field in my DTO that uses a custom type (e.g., CustomLongId), and I'm trying to define a field-specific description with the @Schema annotation. However, the generated OpenAPI documentation only shows a reference to the schema ($ref: #/components/schemas/CustomLongId) and ignores the field-level description that I provided.

Here’s a minimal example of the problem:

Code Example:

public class SharedCustomIdRequestDto {

@Nullable
@Schema(description = "request dto custom long id")
@Valid
private CustomLongId requestCustomLongId;

}
And the custom type:

@Schema(description = "Custom Long id")
public class CustomLongId {
private String value;
}

In the generated OpenAPI documentation, the field requestCustomLongId is represented as a $ref to the CustomLongId schema, but the field-specific description ("request dto custom long id") is lost.

Expected Behavior:
The field-specific description provided in the @Schema annotation ("request dto custom long id") should be shown in the generated OpenAPI documentation for the requestCustomLongId field.
Actual Behavior:
The generated schema references #/components/schemas/CustomLongId, and the field-specific description is not included.

Example of the Generated Schema:

"requestCustomLongId": {
"$ref": "#/components/schemas/CustomLongId",
"description": null
}

Additional Information:
Springdoc Version: 2.6.0
Spring Boot Version: 3.3.3
Java Version: 21

Can you please provide a way to ensure that field-level descriptions are respected even when using a custom type like CustomLongId?
Ideally, the field-level description should visible in generated documentation.

I asked the question in springdoc-openapi repository but they mentioned it is related to swagger-core not springdoc-openapi. Please see springdoc/springdoc-openapi#2723
I tried to solve it via PropertyCustomizer as workaround but still couldn't find description in the provided PropertyCustomizer parameters as input.

Thank you for your support!
Ramazan

[jochenberger]

See also #3900