SpringBoot中java.sql.Timestamp在Swagger显示多字段而非单字段问题

1. 解决Timestamp字段在Swagger中拆分显示的问题 #

在所有java.sql.Timestamp类型字段上添加Jackson的@JsonFormat注解指定统一的时间格式，同时配合Swagger的@Schema注解明确字段为字符串格式的时间戳，避免Swagger将其拆分为多个子字段：

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

// ... 原有注解保留
@Column(name = "creationTimeStamp", insertable = false)
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
@Schema(type = "string", format = "date-time", description = "创建时间戳")
private java.sql.Timestamp creationTimeStamp = new java.sql.Timestamp(System.currentTimeMillis());

@Column(name = "VersionTimeStamp", nullable = false)
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
@Schema(type = "string", format = "date-time", description = "版本时间戳")
private java.sql.Timestamp versionTimeStamp = new java.sql.Timestamp(System.currentTimeMillis());

@Column(name = "ConfirmationTimeStamp", insertable = false)
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
@Schema(type = "string", format = "date-time", description = "确认时间戳")
private java.sql.Timestamp confirmationTimeStamp;

注意：修正了变量名的大小写为Java驼峰命名规范，避免ORM映射和序列化时出现异常。

2. 实现Swagger中的默认值预填充 #

Swagger不会自动识别代码中通过new java.sql.Timestamp(...)设置的默认值，需要通过以下两种方式处理：

• 静态示例值：直接在@Schema注解的example属性中指定时间字符串，比如example = "2024-05-20 14:30:00"
• 动态默认值：在Controller层接收请求后，判断字段是否为null，若为null则设置当前时间戳，同时在Swagger文档的接口描述中说明默认行为。

3. 确保@RequestBody接收JSON时的字段一致性 #

• 保证实体类字段名与JSON字段名匹配，可通过Jackson默认的驼峰转下划线配置，或用@JsonProperty注解明确映射关系
• 在Controller的@RequestBody参数上添加Swagger的@RequestBody注解，明确请求体结构，让Swagger生成正确的JSON输入框而非拆分字段：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TradeDataController {

    @PostMapping("/trade")
    @Operation(summary = "提交交易数据")
    public String submitTrade(@RequestBody @RequestBody(content = @io.swagger.v3.oas.annotations.media.Content(
            schema = @io.swagger.v3.oas.annotations.media.Schema(implementation = TradeData.class)
    )) TradeData tradeData) {
        // 补充默认值逻辑
        if (tradeData.getVersionTimeStamp() == null) {
            tradeData.setVersionTimeStamp(new java.sql.Timestamp(System.currentTimeMillis()));
        }
        return "success";
    }
}

额外优化建议 #

推荐使用Java 8的java.time.LocalDateTime替代java.sql.Timestamp，它线程安全且Swagger对其支持更友好，配合注解可以更顺畅地处理时间字段展示：

import java.time.LocalDateTime;

// 替换原有Timestamp字段
@Column(name = "VersionTimeStamp", nullable = false)
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@Schema(type = "string", format = "date-time", example = "2024-05-20 14:30:00")
private LocalDateTime versionTimeStamp = LocalDateTime.now();

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