SpringBoot3抽象Controller的Swagger3通用注解配置方案咨询

明确说：可行，但没法直接靠Swagger原生注解的动态替换实现，得借助它的扩展机制来做。

核心限制 #

Swagger3的@Operation、@ApiResponse这类注解本身不支持像@Schema(anyOf = ...)那样的动态替换逻辑，而且Java注解的继承机制有局限——只有带@Inherited标记的注解才会被子类继承，但Swagger的这些接口注解大多没加这个标记，就算加了，也没法动态替换注解里的属性值（比如实体类、描述文本）。

实现方案 #

通过Swagger3提供的OperationCustomizer和OpenApiCustomizer扩展接口，结合抽象控制器的泛型信息，就能动态生成适配各业务的接口文档：

1. 给抽象控制器加泛型参数
   先把抽象类改成带泛型的形式，明确返回的业务实体类型：

public abstract class CommonReadOnlyResource<T> {
    @Autowired
    protected CommonReadOnlyService<T> service;

    @GetMapping("/{id}")
    public ResponseEntity<T> findById(@PathVariable Long id) {
        return ResponseEntity.ok(service.findById(id));
    }

    @GetMapping
    public ResponseEntity<List<T>> findAll() {
        return ResponseEntity.ok(service.findAll());
    }
}

业务Controller继承时指定具体实体：

@RestController
@RequestMapping("/users")
public class UserResource extends CommonReadOnlyResource<User> {
}

2. 自定义OperationCustomizer动态修改接口文档
   实现OperationCustomizer接口，通过反射拿到Controller的泛型类型，然后动态设置接口的标签、描述、响应实体等信息：

@Component
public class ReadOnlyResourceOperationCustomizer implements OperationCustomizer {
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        Class<?> controllerClass = handlerMethod.getBeanType();
        // 判断当前接口是否来自通用抽象控制器
        if (CommonReadOnlyResource.class.isAssignableFrom(controllerClass)) {
            Type genericSuperclass = controllerClass.getGenericSuperclass();
            if (genericSuperclass instanceof ParameterizedType parameterizedType) {
                // 获取具体业务实体类
                Class<?> entityClass = (Class<?>) parameterizedType.getActualTypeArguments()[0];
                String entityName = entityClass.getSimpleName();

                // 针对findById接口配置
                if (handlerMethod.getMethod().getName().equals("findById")) {
                    operation.setTags(Collections.singletonList(entityName));
                    operation.setSummary("根据ID查询" + entityName);
                    operation.setDescription("根据唯一ID获取单个" + entityName + "详情");
                    // 修改响应体的Schema指向具体实体
                    operation.getResponses().get("200").getContent().get("application/json")
                            .setSchema(new Schema().$ref("#/components/schemas/" + entityName));
                }
                // 针对findAll接口配置
                else if (handlerMethod.getMethod().getName().equals("findAll")) {
                    operation.setTags(Collections.singletonList(entityName));
                    operation.setSummary("查询所有" + entityName);
                    operation.setDescription("获取全部" + entityName + "列表数据");
                    // 修改响应体为实体集合的Schema
                    operation.getResponses().get("200").getContent().get("application/json")
                            .setSchema(new ArraySchema().items(new Schema().$ref("#/components/schemas/" + entityName)));
                }
            }
        }
        return operation;
    }
}

3. 全局通用响应配置（可选）
   如果要统一处理404、500这类通用响应，可以用OpenApiCustomizer添加全局模板：

@Component
public class CommonApiResponseCustomizer implements OpenApiCustomizer {
    @Override
    public void customise(OpenAPI openApi) {
        ApiResponse notFound = new ApiResponse().description("资源不存在");
        ApiResponse serverError = new ApiResponse().description("服务器内部错误");
        // 给所有接口添加通用响应码描述
        openApi.getPaths().values().forEach(pathItem ->
                pathItem.readOperations().forEach(operation ->
                        operation.getResponses()
                                .addApiResponse("404", notFound)
                                .addApiResponse("500", serverError)
                )
        );
    }
}

额外提醒 #

• 这种方式不用在抽象类上写死Swagger注解，所有业务Controller继承后会自动生成适配的文档；
• 确保SpringBoot3.1.3搭配的springdoc-openapi版本在2.2.0及以上（适配Java17和SpringBoot3）；
• 如果需要业务自定义描述，可以给抽象类加个抽象方法让子类返回自定义文本，再在Customizer里调用获取。

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