Spring中如何在Swagger请求体隐藏实体属性且其他场景保留显示

我之前处理过类似的需求，核心就是要让同一个User实体在不同Swagger接口中展示不同的字段，给你几个实用的解决方案，按推荐度排序：

1. 最佳实践：使用DTO（数据传输对象） #

这是最直观也最易维护的方案，通过创建专门的请求对象来解耦接口请求和实体类，避免实体类被各种场景的注解污染。

步骤： #

1. 创建CreateUserRequest类，只包含创建用户所需的字段：

public class CreateUserRequest {
    private Integer id;
    private String name;

    // Getters and Setters
}

2. 修改UserResource控制器的接口方法，用新的DTO作为请求体：

@PostMapping(value = "/")
public ResponseEntity<StatusResponse> createUser(@RequestBody CreateUserRequest userRequest) {
    // 将DTO转换为User实体
    User user = new User();
    user.setId(userRequest.getId());
    user.setName(userRequest.getName());
    // 后续业务逻辑...
}

优势： #

• 彻底隔离不同接口的字段需求，后续修改创建接口的字段时，不会影响其他使用User实体的场景
• 代码语义更清晰，一眼就能看出创建用户需要哪些参数

2. 使用Swagger分组注解（无需新增类） #

如果不想额外创建DTO，可以利用Swagger的分组功能，通过注解标记字段在哪些分组中显示/隐藏。

步骤（以OpenAPI 3.0为例，对应SpringDoc）： #

1. 定义一个分组标记接口：

public interface CreateUserGroup {}

2. 修改User实体类的department字段注解，指定仅在CreateUserGroup分组中隐藏：

public class User {
    private Integer id;
    private String name;
    
    @Schema(hidden = true, groups = CreateUserGroup.class)
    private String department;
    
    // 其他字段及getters/setters
}

3. 在控制器的创建用户方法上，指定Swagger使用该分组：

@PostMapping(value = "/")
@Operation(summary = "创建用户")
public ResponseEntity<StatusResponse> createUser(
        @RequestBody @Validated(CreateUserGroup.class) User user) {
    // 业务逻辑...
}

如果你用的是旧版Swagger（SpringFox），可以把@Schema换成@ApiModelProperty(groups = CreateUserGroup.class, hidden = true)，效果一致。

3. 结合Jackson的@JsonView #

利用Jackson的视图功能，配合Swagger的支持，也能实现字段的按需展示。

步骤： #

1. 定义视图接口：

// 创建用户时的视图（仅显示id和name）
public interface CreateUserView {}
// 其他场景的视图（显示所有字段）
public interface FullUserView extends CreateUserView {}

2. 在User实体类上标记字段对应的视图：

public class User {
    @JsonView(CreateUserView.class)
    private Integer id;
    
    @JsonView(CreateUserView.class)
    private String name;
    
    @JsonView(FullUserView.class)
    private String department;
    
    // 其他字段及getters/setters
}

3. 在控制器方法上指定使用的视图：

@PostMapping(value = "/")
@JsonView(CreateUserView.class)
public ResponseEntity<StatusResponse> createUser(
        @RequestBody @JsonView(CreateUserView.class) User user) {
    // 业务逻辑...
}

4. 配置Swagger支持JsonView（以SpringDoc为例）：

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSchemas("User_Create", createSchema(User.class, CreateUserView.class))
                        .addSchemas("User_Full", createSchema(User.class, FullUserView.class)));
    }

    private Schema<?> createSchema(Class<?> clazz, Class<?> view) {
        ObjectMapper mapper = new ObjectMapper();
        mapper.configure(MapperFeature.DEFAULT_VIEW_INCLUSION, false);
        mapper.setConfig(mapper.getSerializationConfig().withView(view));
        return Json.mapper().convertValue(
                mapper.getSerializationConfig().introspect(BasicBeanDescription.forClass(clazz)).findProperties(),
                Schema.class
        );
    }
}

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