kotlin - 为什么 Swagger 不检测可选的 JSON 属性？

Question

我有以下类(class):

import com.fasterxml.jackson.annotation.JsonProperty
import org.joda.time.DateTime
import org.joda.time.DateTimeZone

data class Entity(
        val email: String,
        val name: String,
        val birthDate: DateTime,
        @JsonProperty(required = false) val gender: Gender? = null,
        @JsonProperty(required = false) val country: String? = null,
        val locale: String,
        val disabled: Boolean = false,
        @JsonProperty(required = false) val createdAt: DateTime = DateTime(DateTimeZone.UTC),
        val role: Role,
        val entityTypeId: Long,
        val entityTypeAttributes: MutableMap<String, Any> = HashMap(),
        val medicalSpecialityId: Long? = null,
        val id: Long? = null
)

有些属性不是必需的，因为它们要么可以为 null(性别、国家/地区)，要么具有默认值 (createdAt)。

但是生成的swagger文档如下:

 "components": {
    "schemas": {
      "Entity": {
        "required": [
          "birthDate",
          "createdAt", <------------ Notice here!
          "disabled",
          "email",
          "entityTypeAttributes",
          "entityTypeId",
          "locale",
          "name",
          "role"
        ],
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "birthDate": {
            "type": "string",
            "format": "date-time"
          },
          "gender": {
            "type": "string",
            "enum": [
              "MALE",
              "FEMALE",
              "OTHER"
            ]
          },
          "country": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "disabled": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "role": {
            "type": "string",
            "enum": [
              "ADMIN",
              "DOCTOR",
              "PATIENT"
            ]
          },
          "entityTypeId": {
            "type": "integer",
            "format": "int64"
          },
          "entityTypeAttributes": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          },
          "medicalSpecialityId": {
            "type": "integer",
            "format": "int64"
          },
          "id": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
   (...)

因此，就文档而言，它表明 createdAt 是强制性的(这不是真的)...

Generated Swagger docs

我正在使用 Kotlin、Javalin 和 OpenAPI (io.javalin.plugin.openapi) Javalin 集成。

我不知道我还需要做什么才能让 OpenAPI 明白 createdAt 是可选的...

Answer 1

我的猜测是，kotlin 实现使用可空性作为发现必需属性并忽略必需属性的方法。例如，您实际上不需要性别和国家/地区的注释。

显然这并不理想，但是如果将 creadtedAt 更改为 DateTime 呢？它不会按要求显示。

这可能是 javalin 引入的 kotlin openapi 文档工具的错误。