Java8+SpringBoot1.5环境下如何在SpringDoc OpenAPI中隐藏父类字段？

我使用Java 8、Spring Boot 1.5.1版本，已引入以下依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

我的控制器请求类均继承自一个包含若干字段的父类，希望在OpenAPI文档中忽略这些父类字段，仅显示子类字段，但尝试了以下方法均无效：

• 在基请求类上添加@Schema(all = {})注解；
• 创建OpenApiCustomizer Bean，但该方式需要springdoc-openapi-starter-webmvc-ui及Java 17；
• 在yml配置中添加springdoc.packages-to-exclude=packageWithOnlyTheSuperRequestClass。

相关代码示例：

@RestController
public class FakeController{

    @RequestMapping(value = {"/fake-method"}, method = RequestMethod.GET)
    public String fakeMethod(BaseClassRequest request){
        return "Hello, world!";
    }

}

public class BaseClassRequest extends SuperClassRequest{

    private String username;

    // getter and setter
}

public class SuperClassRequest{
    private String password;

    // getter and setter
}

针对你使用的旧版本环境（Java 8、Spring Boot 1.5.1、springdoc-openapi-ui 1.8.0），以下两种方案可以有效忽略父类字段：

方案1：给父类字段添加@Schema(hidden = true) #

直接在父类需要隐藏的字段上标注@Schema(hidden = true)，springdoc生成文档时会自动忽略该字段。修改父类代码如下：

import io.swagger.v3.oas.annotations.media.Schema;

public class SuperClassRequest{
    @Schema(hidden = true)
    private String password;

    // getter and setter
}

这种方式简单直接，适合父类字段固定需要隐藏的场景。

方案2：自定义ModelConverter批量过滤父类字段 #

如果父类被多个子类继承，且不想逐个修改父类字段注解，可以通过自定义ModelConverter批量过滤父类的所有字段：

1. 创建自定义转换器类：

import io.swagger.v3.core.converter.ModelConverter;
import io.swagger.v3.core.converter.ModelConverterContext;
import io.swagger.v3.oas.models.media.Schema;
import java.lang.reflect.Field;
import java.util.Iterator;
import java.util.List;

public class SuperClassFieldFilterConverter implements ModelConverter {

    @Override
    public Schema resolve(AnnotatedType annotatedType, ModelConverterContext context, Iterator<ModelConverter> chain) {
        Schema schema = chain.next().resolve(annotatedType, context, chain);
        if (schema == null) {
            return null;
        }
        Class<?> clazz = annotatedType.getType().getErasedType();
        // 仅处理继承自SuperClassRequest的子类
        if (SuperClassRequest.class.isAssignableFrom(clazz) && !clazz.equals(SuperClassRequest.class)) {
            // 获取父类所有字段名
            List<Field> superFields = List.of(SuperClassRequest.class.getDeclaredFields());
            // 从文档Schema中移除父类字段
            superFields.forEach(field -> schema.getProperties().remove(field.getName()));
        }
        return schema;
    }
}

2. 注册转换器到springdoc：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.core.converter.ModelConverters;

@Configuration
public class SpringDocConfig {

    @Bean
    public void registerSuperClassFieldFilter() {
        ModelConverters.getInstance().addConverter(new SuperClassFieldFilterConverter());
    }
}

该方案会自动过滤所有继承自SuperClassRequest的子类在OpenAPI文档中的父类字段，无需修改实体类代码。

无效方案说明 #

• @Schema(all = {})：在springdoc-openapi-ui 1.8.0版本中，该注解没有忽略父类字段的作用；
• OpenApiCustomizer：属于springdoc新版本（starter系列）的API，你的旧版本环境不支持；
• springdoc.packages-to-exclude：用于排除整个包下的类被扫描，但你的父类被子类继承，无法通过该配置单独隐藏父类字段。

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