OpenApi无法识别@Schema注解配置的example属性问题

这个问题是Swagger/Springdoc内置类型映射优先级高于字段注解配置导致的：

• 框架对OffsetDateTime、LocalDateTime这类Java时间类型有固定的内置映射规则，默认会直接将其识别为string类型、date-time格式，会直接覆盖字段上@Schema注解配置的type、format、example、pattern属性
• 配置的@JsonDeserialize仅参与Jackson的JSON序列化/反序列化流程，Swagger扫描类生成Schema时默认不会感知自定义反序列化器的逻辑，不会自动调整字段的Schema规则
• 注解里写的type = "Date"本身不符合OpenAPI规范，OpenAPI的原生类型仅包含string/number/integer/boolean/object/array六种，不存在Date类型，错误的类型声明也会让框架直接忽略该字段上的其他Schema配置。

按落地成本从低到高排序：

方案1：单字段配置修正（最常用） #

修改字段上的@Schema注解，修正错误的type值，同时添加implementation属性显式指定按字符串类型生成Schema，绕开OffsetDateTime的内置映射规则：

@NotNull
@Schema(
    description = "blahblah",
    example = "19680228",
    type = "string", // 修正原来错误的"Date"类型值
    pattern = "([0-9]{4})(?:[0-9]{2})([0-9]{2})",
    requiredMode = Schema.RequiredMode.REQUIRED,
    nullable = false,
    implementation = String.class // 强制框架按String类型生成该字段Schema，不触发内置时间类型映射
)
@JsonDeserialize(using = CustomDateDeserializer.class)
private OffsetDateTime birthDate;

修改后重启服务，访问/api-docs.yaml即可看到字段的example、pattern配置都正常生成，Swagger UI的示例值也会展示为19680228。

方案2：全局规则配置（适合多字段复用场景） #

如果项目中有大量相同格式的日期字段，可以通过全局配置替换框架默认的时间类型映射逻辑，不用逐字段加注解：

@Configuration
public class OpenApiConfig {
    @Bean
    public ModelResolver customModelResolver(ObjectMapper objectMapper) {
        return new ModelResolver(objectMapper) {
            @Override
            protected Schema<?> resolve(JavaType type, ModelConverterContext context, Iterator<ModelConverter> next) {
                // 可根据自身业务加判断逻辑，比如带特定注解的OffsetDateTime字段才走自定义格式
                if (type.getRawClass().equals(OffsetDateTime.class)) {
                    return new StringSchema()
                            .pattern("([0-9]{4})(?:[0-9]{2})([0-9]{2})")
                            .example("19680228");
                }
                return super.resolve(type, context, next);
            }
        };
    }
}

方案3：直接声明完整Schema（适合复杂字段配置） #

如果字段Schema配置逻辑复杂，可以用@SchemaObject注解直接定义完整Schema，该注解优先级高于框架内置类型映射：

@NotNull
@JsonDeserialize(using = CustomDateDeserializer.class)
@SchemaObject(
        description = "blahblah",
        example = "19680228",
        type = "string",
        pattern = "([0-9]{4})(?:[0-9]{2})([0-9]{2})",
        required = true,
        nullable = false
)
private OffsetDateTime birthDate;

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