java - 用 Swagger 表示 ISO 8601 年月日期文档

Question

如何让 Swagger 核心生成 openapi.json 文档，其中 Year-Month 字段表示为 String？

在代码中，我已经尝试过 @JsonFormat 和 @JsonbDateFormat。

返回的实体正确表示为字符串，格式正确，但文档始终生成为对象。

环境:

• io.swagger.core.v3.swagger-jaxrs2 2.1.9
• 野蝇 21.0.2
• Java 11

这里是一个片段:

@JsonbDateFormat(value = "uuuu-MM") // or "yyyy-MM", or @JsonFormat(shape = Shape.STRING, pattern = "uuuu-MM")
private YearMonth reference;

实体返回:

{
    "reference": "2020-11",
}

生成的文档:

{
  "openapi" : "3.0.1",
  ...
  "components" : {
    "schemas" : {
      "Entity" : {
        "type" : "object",
        "properties" : {
          "reference" : {
            "type" : "object",
            "properties" : {
              "year" : {
                "type" : "integer",
                "format" : "int32"
              },
              "month" : {
                "type" : "string",
                "enum" : [ "JANUARY", "FEBRUARY", "MARCH", "APRIL", "MAY", "JUNE", "JULY", "AUGUST", "SEPTEMBER", "OCTOBER", "NOVEMBER", "DECEMBER" ]
              },
              "monthValue" : {
                "type" : "integer",
                "format" : "int32"
              },
              "leapYear" : {
                "type" : "boolean"
              }
            }
          }
        }
      }
    }
  }
}

Answer 1

显然 Swagger 核心不使用 @JsonFormat 或 @JsonbDateFormat 作为格式化模板的来源，它只使用属性类型，但它没有 YearMonth 类型的默认值.

因此，可以使用 Swagger Annotation @Schema 定义数据表示。

在这种特殊情况下:@Schema(type = "string", format = "yearmonth", example = "2020-07")