Description
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