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

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 https://github.com/springdoc/springdoc-openapi/issues/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

Oct 02 '24 20:10 ramazangirgin