时间戳

首页 > 解决方案 > 为什么 Swagger 不检测可选的 JSON 属性？

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

问题描述

我有以下课程：

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
)

有些属性不是必需的，因为它们要么可以为空（性别、国家/地区），要么具有默认值（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是强制性的（这是不正确的）......

生成的 Swagger 文档

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

我不知道我还需要什么才能让 OpenAPI 理解这createdAt是可选的......

标签： kotlinjacksonopenapijavalin

解决方案

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

显然这并不理想，但是如果你把 credtedAt 改成 DateTime 呢？它不会按要求显示。

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

推荐阅读