如何结合@JsonView实现Swagger接口文档属性的条件隐藏？

完全可以通过@JsonView实现Swagger文档按需展示不同接口的响应属性，Springfox（Swagger Spring集成框架）2.6.0+版本、SpringDoc（OpenAPI 3官方推荐实现）都原生支持该能力，无需自定义扩展插件，操作步骤如下： #

步骤1：定义视图区分接口场景 #

先定义标记用的视图接口，用于区分不同接口的属性可见范围：

public class View {
    // 接口A专属视图
    public interface ApiA {}
    // 接口B专属视图
    public interface ApiB {}
}

如果需要实现属性继承（比如接口B要包含接口A的所有可见属性），可以让视图接口继承：

public interface ApiB extends ApiA {}

步骤2：给实体类属性绑定视图 #

给响应实体的属性标注@JsonView，指定该属性可以在哪些视图下展示：

public class CommonResponse {
    // 两个接口都展示的属性，绑定两个视图
    @JsonView({View.ApiA.class, View.ApiB.class})
    @ApiModelProperty("通用主键ID")
    private Long id;

    // 仅在接口A展示的属性
    @JsonView(View.ApiA.class)
    @ApiModelProperty("仅接口A返回的敏感字段")
    private String sensitiveFieldForA;

    // 仅在接口B展示的属性
    @JsonView(View.ApiB.class)
    @ApiModelProperty("仅接口B返回的扩展字段")
    private String extFieldForB;
}

步骤3：给接口方法绑定对应视图 #

在Controller的接口方法上标注@JsonView，指定该接口使用的视图，Swagger会自动过滤模型属性：

@RestController
@RequestMapping("/api")
public class DemoController {
    // 接口A的文档只会展示绑定了ApiA视图的属性
    @GetMapping("/a")
    @JsonView(View.ApiA.class)
    public CommonResponse getApiAData() {
        // 业务逻辑
        return new CommonResponse();
    }

    // 接口B的文档只会展示绑定了ApiB视图的属性
    @GetMapping("/b")
    @JsonView(View.ApiB.class)
    public CommonResponse getApiBData() {
        // 业务逻辑
        return new CommonResponse();
    }
}

注意事项 #

• 不要给属性加@ApiModelProperty(hidden = true)，否则该属性会在所有接口的文档中全局隐藏，和视图配置无关
• 没有标注任何@JsonView的属性默认会在所有视图下展示，需要全局隐藏的属性才可以加hidden = true
• Springfox 3.x+默认开启JsonView支持，如果是低版本可以在配置文件中手动开启：

springfox:
  documentation:
    json-view-enabled: true

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