Spring Doc Open API 在 swagger ui 上显示无效的字段名称

Question

赏金将在 6 天后到期。 此问题的答案有资格获得+50声望赏金。 Mateusz Stefaniak希望引起对这个问题的更多关注。

当字段名称的开头只有一个小写字母时，swagger UI 上显示的 model 无效。

我的 Kotlin model：

class TrendEvaluationModel(
    val xAxisValue: Int,
    val yAxisValue: Int,
    val customValue: Int?
)

swagger UI 上显示的内容：

{
  "customValue": 1,
  "xaxisValue": 1,
  "yaxisValue": 1
}

我试过了：

1. 具有指定name属性的@Parameter注释，但它不起作用。
2. 具有指定name属性的@Schema注释，但它不起作用。
3. @JsonProperty("xAxisValue")并且它工作但没有按预期工作 - swagger 上的 model 显示了两个字段（ xaxisValue和xAxisValue ），但我只需要其中一个（ xAxisValue ）。

感谢你的帮助。

注意：如果字段名称的开头有两个或多个小写字母，则没有问题

Answer 1

将@Schema注解应用于构造函数字段以更改 Swagger UI 中的字段名称没有效果。 所以我将这些字段设为私有并添加了指向私有字段的新字段。 我还在新字段中添加了@Schema和@JsonProperty注释，以分别更改它们在 Swagger UI 和 API 请求/响应中的显示方式。 最终的 class 如下所示：

import com.fasterxml.jackson.annotation.JsonProperty
import io.swagger.v3.oas.annotations.media.Schema

class TrendEvaluationModel(
    @Schema(hidden = true)
    private val xAxisVal: Int,
    @Schema(hidden = true)
    private val yAxisVal: Int,
    val customValue: Int?
) {
    val xAxisValue: Int
        @Schema(name = "xAxisValue")
        @JsonProperty("xAxisValue")
        get() = xAxisVal

    val yAxisValue: Int
        @Schema(name = "yAxisValue")
        @JsonProperty("yAxisValue")
        get() = yAxisVal
}

此 class 在 Swagger UI 中显示如下，具有正确的字段名称：

{
  "customValue": 0,
  "xAxisValue": 0,
  "yAxisValue": 0
}

您可以在 github 上找到使用此class的工作示例应用程序