Spring Boot中如何让Swagger UI隐藏自动更新的实体字段

现有场景说明 #

• 基于JPA的实体通过@MappedSuperclass抽取公共自动维护字段：createdAt、updatedAt由Hibernate根据操作时间自动填充，前端无需在新增接口请求中传入
• 目前Swagger UI在POST /jokes新增接口的请求体面板中，默认展示了上述自动字段的输入项，需要从文档展示层移除这类非前端可控的字段

可落地的实现方案 #

方案1：字段级注解隐藏（适合不需要在响应中展示自动字段的场景） #

如果接口响应中也不需要返回createdAt、updatedAt这类内部维护字段，直接在公共父类的对应字段上加Swagger的隐藏注解即可，全局一次配置就对所有继承BaseEntity的实体生效：

• 若使用 SpringDoc OpenAPI（Swagger 3.x 以上版本），改造后的BaseEntity代码：

@Data
@MappedSuperclass
public abstract class BaseEntity {

  @Column(updatable = false)
  @CreationTimestamp
  @Schema(hidden = true)
  private LocalDateTime createdAt;

  @UpdateTimestamp
  @Schema(hidden = true)
  private LocalDateTime updatedAt;
}

• 若使用 Springfox（Swagger 2.x 老版本），将上述注解替换为@ApiModelProperty(hidden = true)即可。

这种方式仅修改文档展示层逻辑，不会改动JPA字段映射、SpringMVC参数绑定的现有运行逻辑，业务行为完全不受影响。

方案2：单独配置请求体Schema过滤（适合需要在响应中展示自动字段的场景） #

如果业务要求接口响应中需要正常返回createdAt、updatedAt给前端，只是不希望前端在请求入参中填写这些字段，就不能直接给字段加全局隐藏注解（否则响应里的字段也会被隐藏）。此时可以在控制器的新增接口上，单独针对请求体的Schema配置要排除的字段：

@PostMapping("/jokes")
@Operation(requestBody = @RequestBody(
    content = @Content(schema = @Schema(
        // 从请求体Schema中排除所有非前端可控的自动字段
        not = {
            "id",
            "createdAt",
            "updatedAt"
        }
    ))
))
public Joke createJoke(@Valid @RequestBody Joke joke) {
  return jokeRepository.save(joke);
}

配置完成后，Swagger渲染的新增接口请求体会自动排除指定字段，而响应Schema的展示不受任何影响，依然会完整返回所有实体字段。

方案3：请求DTO隔离（大型项目常用解耦方案） #

如果项目规模较大，可以单独为新增接口定义独立的请求DTO，只包含需要前端传入的字段（比如Joke的content），控制器入参直接使用DTO代替实体类：

• 定义JokeCreateRequest类，仅包含content字段
• 修改控制器方法入参类型，从实体类Joke替换为JokeCreateRequest
• 在业务逻辑层将DTO的参数映射到实体类对象上，再调用Repository完成保存

这种方式完全实现了接口入参与数据库实体的解耦，后续接口字段调整不会直接影响数据库实体结构，缺点是需要额外维护DTO到实体的映射关系。

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