Swagger日期时间字段示例值与API实际返回不符，如何通过注解修正？

当然可以通过Java注解解决这个问题！Swagger默认不会自动识别Jackson的@JsonFormat注解来同步字段的示例值和格式描述，所以我们需要配合Swagger自身的注解来覆盖默认配置，而且完全不需要修改外部的Swagger描述文件。

下面分两种常见的Swagger版本给出具体实现：

1. 如果你用的是OpenAPI 3.x（对应SpringDoc OpenAPI或Swagger 3） #

直接在lastModifiedDate字段上添加@Schema注解，显式指定匹配实际返回格式的示例值和格式类型：

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

// ...

@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX", timezone="America/New_York")
@Schema(
    example = "2020-07-09T07:44:35.366-04:00",
    type = "string",
    format = "date-time"
)
private Date lastModifiedDate;

2. 如果你用的是Swagger 2.x（对应Springfox Swagger） #

则使用@ApiModelProperty注解来实现同样的效果：

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModelProperty;
import java.util.Date;

// ...

@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX", timezone="America/New_York")
@ApiModelProperty(
    example = "2020-07-09T07:44:35.366-04:00",
    dataType = "string"
)
private Date lastModifiedDate;

为什么这样有效？ #

Swagger的默认date-time示例是UTC格式的2020-07-09T12:50:48.461Z，但它不会主动解析Jackson的时区和格式配置。通过显式添加Swagger注解，我们直接告诉Swagger该字段的实际示例值和格式类型，这样Swagger UI展示的内容就会和API实际返回的格式完全一致了。

如果你用的是Spring Boot + SpringDoc OpenAPI，也可以通过配置让框架自动适配Jackson的日期格式，但显式添加注解是最直接、不需要额外配置的方式，完全符合你“仅通过Java注解实现”的需求。

内容的提问来源于stack exchange，提问作者peter.petrov