Spring Boot中Swagger/OpenAPI v3不识别LocalTime为字符串的问题

针对Spring Boot 3.3.2 + Java 17 + Springdoc OpenAPI v3场景下，DTO中LocalTime字段被Swagger识别为对象结构的问题，可通过以下几种方案解决：

方案一：自定义ModelConverter覆盖默认类型映射（推荐） #

Springdoc默认对Java 8时间类型的解析逻辑会生成包含hour、minute等属性的对象结构，我们可以通过自定义ModelConverter强制将LocalTime映射为字符串类型：

import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.core.converter.ModelConverterImpl;
import io.swagger.v3.core.converter.ResolvedSchema;
import io.swagger.v3.oas.models.media.Schema;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.lang.reflect.Type;
import java.time.LocalTime;
import java.util.Iterator;

@Configuration
public class OpenApiCustomConfig {
    @Bean
    public ModelConverter localTimeStringConverter() {
        return new ModelConverterImpl() {
            @Override
            public Schema resolve(Type type, ModelConverterContext context, Iterator<ModelConverter> chain) {
                // 匹配LocalTime类型
                if (type instanceof Class<?> clazz && LocalTime.class.isAssignableFrom(clazz)) {
                    Schema<String> stringSchema = new Schema<>();
                    stringSchema.setType("string");
                    stringSchema.setPattern("HH:mm:ss");
                    stringSchema.setExample("09:30:00"); // 给Swagger UI添加示例
                    return stringSchema;
                }
                // 其他类型走默认逻辑
                return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
            }
        };
    }
}

方案二：确保注解组合与Springdoc配置生效 #

如果不想自定义Converter，可以调整注解和Springdoc配置，让Jackson注解被正确解析：

1. DTO字段注解组合：同时保留@JsonFormat和@Schema，明确指定类型和格式：

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.v3.oas.annotations.media.Schema;
import java.time.LocalTime;

public class EntryDTO {
    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "HH:mm:ss")
    @Schema(type = "string", pattern = "HH:mm:ss", example = "08:15:00")
    private LocalTime entryTime;

    // 省略getter/setter
}

2. 开启Springdoc的Jackson注解解析：在application.yml中添加配置，确保Springdoc会读取Jackson的注解信息：

springdoc:
  model-converters:
    jackson:
      enabled: true

方案三：全局Jackson配置（辅助保障序列化/反序列化） #

为了确保整个应用对LocalTime的序列化/反序列化统一为字符串格式，可在application.yml中配置Jackson：

spring:
  jackson:
    time-zone: GMT+8
    serialization:
      write-dates-as-timestamps: false # 禁用时间戳格式
    format:
      date-time: HH:mm:ss # 全局时间字符串格式

注意事项 #

• 若之前单独加@Schema或@JsonFormat无效，是因为Springdoc的默认类型转换器优先级高于Jackson注解解析，自定义Converter可以直接覆盖默认逻辑；
• 手动传入字符串能正常解析，说明Jackson的序列化/反序列化逻辑是正常的，问题仅出在Swagger的文档生成和请求体渲染层面。

内容的提问来源于stack exchange，提问作者null-point-exceptional