Swagger中OffsetDateTime默认响应格式错误的批量解决方案咨询

方案1：SpringDoc全局配置自定义日期示例 #

如果使用SpringDoc（OpenAPI 3.x），可通过全局配置类批量修正所有OffsetDateTime字段的Swagger示例：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.media.Schema;
import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Map;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenApiCustomizer dateSchemaCustomizer() {
        return openApi -> {
            Map<String, Schema> schemas = openApi.getComponents().getSchemas();
            if (schemas == null) return;

            // 匹配你接口实际返回的日期格式
            DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX");
            String standardExample = OffsetDateTime.now().format(formatter);

            // 遍历所有Schema，批量设置OffsetDateTime类型字段的示例和格式描述
            schemas.values().forEach(schema -> {
                if (schema.getProperties() != null) {
                    schema.getProperties().values().forEach(propertySchema -> {
                        if ("string".equals(propertySchema.getType()) 
                            && "offset-date-time".equals(propertySchema.getFormat())) {
                            propertySchema.setExample(standardExample);
                            propertySchema.setFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX");
                        }
                    });
                }
            });
        };
    }
}

方案2：自定义SchemaProcessor批量处理类型 #

利用SpringDoc提供的SchemaProcessor接口，针对OffsetDateTime类型统一生成Schema规则：

import io.swagger.v3.core.converter.AnnotatedType;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.Schema;
import org.springdoc.core.providers.SchemaProcessor;
import org.springframework.stereotype.Component;

import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;

@Component
public class OffsetDateTimeSchemaProcessor implements SchemaProcessor {

    // 与接口返回格式一致的格式化规则
    private static final DateTimeFormatter DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX");

    @Override
    public Schema process(Schema schema, AnnotatedType type, ModelConverterContext context) {
        if (OffsetDateTime.class.isAssignableFrom(type.getType())) {
            schema.setExample(OffsetDateTime.now().format(DATE_FORMATTER));
            schema.setFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX");
        }
        return schema;
    }
}

这个处理器会在Swagger生成Schema时，自动对所有OffsetDateTime字段应用统一配置，无需修改任何实体类字段。

方案3：结合Jackson配置与Swagger属性定制 #

先通过Jackson统一接口返回的日期格式，再同步到Swagger文档中：

1. 在application.yml配置Jackson的日期序列化规则：

spring:
  jackson:
    serialization:
      write-dates-as-timestamps: false
    formatter:
      date-time: "yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX"

2. 添加Swagger属性定制类，同步格式到文档：

import io.swagger.v3.oas.models.media.StringSchema;
import org.springdoc.core.customizers.PropertyCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.time.OffsetDateTime;

@Configuration
public class OpenApiConfig {

    @Bean
    public PropertyCustomizer offsetDateTimePropertyCustomizer() {
        return (propertySchema, property) -> {
            if (OffsetDateTime.class.isAssignableFrom(property.getType())) {
                StringSchema stringSchema = (StringSchema) propertySchema;
                stringSchema.setExample("2022-11-01T11:11:11.715018+03.00");
                stringSchema.setFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX");
            }
            return propertySchema;
        };
    }
}

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