如何通过注解让Swagger将自定义序列化类识别为字符串类型

你之前尝试用@ApiParam没效果是因为这个注解是用来标注请求参数（比如接口方法里的@RequestParam参数）的，而模型类的字段需要用专门的模型注解来指定Swagger的类型映射。下面给你几个可行的方案：

方案1：给字段/Getter标注模型类型注解 #

根据你使用的Swagger版本选择对应的注解：

• 如果是Swagger 3.x（OpenAPI 3规范），用@Schema注解：

import io.swagger.v3.oas.annotations.media.Schema;

public class YourRestApiModel {
    // 直接在字段上标注，或者在getter方法上标注都可以
    @Schema(type = "string", example = "2024-06") // 可以加示例值方便前端理解
    private MonthUtil targetMonth;

    public MonthUtil getTargetMonth() {
        return targetMonth;
    }
}

• 如果是Swagger 2.x，用@ApiModelProperty注解：

import io.swagger.annotations.ApiModelProperty;

public class YourRestApiModel {
    @ApiModelProperty(dataType = "string", example = "2024-06")
    private MonthUtil targetMonth;

    // getter...
}

这个方法最直接，适合单个字段或少量模型类的场景。

方案2：全局配置ModelConverter（所有MonthUtil都自动识别为字符串） #

如果你有很多模型类用到了MonthUtil，不想逐个加注解，可以实现Swagger的ModelConverter接口，全局把MonthUtil类型映射为字符串类型：

import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.core.converter.AnnotatedType;
import org.springframework.stereotype.Component;
import java.util.Iterator;

@Component
public class MonthUtilSwaggerConverter implements ModelConverter {
    @Override
    public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterator<ModelConverter> chain) {
        // 判断当前处理的类型是否是MonthUtil
        if (type.getType() instanceof Class && MonthUtil.class.isAssignableFrom((Class<?>) type.getType())) {
            StringSchema stringSchema = new StringSchema();
            stringSchema.setExample("2024-06"); // 设置示例值
            return stringSchema;
        }
        // 不是MonthUtil的话，交给后续转换器处理
        return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
    }
}

把这个类注册为Spring Bean（比如加@Component），Swagger扫描到后就会自动处理所有MonthUtil类型的字段，统一显示为字符串。

方案3：结合Jackson的类型信息（可选） #

如果你已经用Jackson的自定义序列化器/反序列化器把MonthUtil转成字符串，也可以让Swagger复用Jackson的类型映射。比如在MonthUtil类上直接标注@Schema(type = "string")，这样所有引用这个类的地方都会自动识别：

@Schema(type = "string", example = "2024-06")
public class MonthUtil {
    // 你的类逻辑...
}

这个方法适合希望从类本身定义Swagger类型的场景。

内容的提问来源于stack exchange，提问作者Alex R