如何让Swagger Core生成YearMonth字段为字符串类型的OpenAPI文档

Swagger Core默认的模型解析逻辑不会读取Jackson/JsonB的序列化配置，仅会根据YearMonth类本身的字段结构解析为对象类型，所以会出现实际返回是字符串但文档标注为对象的不一致问题。

方案1：单字段单独配置（适合少量YearMonth字段场景） #

直接在对应字段上添加Swagger原生的@Schema注解，强制指定类型为字符串，示例代码如下：

@Schema(type = "string", format = "year-month", example = "2020-11")
@JsonbDateFormat(value = "uuuu-MM") // 原有序列化注解保留即可
private YearMonth reference;

方案2：全局配置（适合项目中存在大量YearMonth字段场景） #

自定义Swagger模型转换器，全局指定所有YearMonth类型都解析为字符串格式：

1. 实现自定义模型转换器

import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.StringSchema;
import java.time.YearMonth;
import java.util.Iterator;

public class YearMonthSchemaConverter implements ModelConverter {
    @Override
    public io.swagger.v3.oas.models.media.Schema resolve(AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain) {
        if (YearMonth.class.equals(type.getType())) {
            return new StringSchema()
                    .format("year-month")
                    .example("2020-11");
        }
        return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
    }
}

2. 注册转换器到Swagger配置
   在项目的Swagger初始化逻辑中添加如下代码：

import io.swagger.v3.core.converter.ModelConverters;

// 在OpenAPI实例初始化后调用
ModelConverters.getInstance().addConverter(new YearMonthSchemaConverter());

配置完成后生成的openapi.json中对应字段会自动标注为字符串类型：

"reference": {
  "type": "string",
  "format": "year-month",
  "example": "2020-11"
}

内容的提问来源于stack exchange，提问作者Claudio Weiler