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

[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.

Thank you for your support! Ramazan

[bnasslahsen]

@ramazangirgin,

This is not handled in sprindoc-openapi. You can use PropertyCustomizer as workaround, to cusotmize the name of your property.

The following code, shows, it's handled in the swagger-core level.

        ResolvedSchema resolvedSchema = ModelConverters.getInstance()
                .resolveAsResolvedSchema(new AnnotatedType(SharedCustomIdRequestDto.class).resolveAsRef(false));

        String description = resolvedSchema.referencedSchemas.get("CustomLongId").getDescription();
        Assert.isTrue("request dto custom long id".equals(description), "Description does not match");

Feel free to ask the swagger-core team for any other help.

[ramazangirgin]

@bnasslahsen thank you for the response. I tried to solve it via PropertyCustomizer as workaround but still couldn't find description in the provided PropertyCustomizer parameters as input. Asked in swagger-core , lets wait for the answer. https://github.com/swagger-api/swagger-core/issues/4753

Ramazan