如何使用Springfox为部分而非全部REST端点配置全局响应？

我之前也遇到过类似的场景，Springfox的全局响应配置确实容易因为范围太广或者匹配问题达不到预期，给你两个可行的方案，你可以根据自己的偏好选择：

方案一：自定义注解 + OperationCustomizer（推荐） #

这种方式不需要拆分API分组，通过自定义注解标记需要共享401响应的方法，然后全局配置中自动为这些方法添加响应，既避免重复代码，又能精准控制范围。

步骤1：创建自定义注解 #

先定义一个标记用的注解，用来标识需要添加共享401响应的方法：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Shared401Response {
}

步骤2：配置Swagger的OperationCustomizer #

在Swagger的Docket配置中，添加一个OperationCustomizer，扫描带有自定义注解的方法并自动注入401响应：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("你的控制器所在包路径"))
            .paths(PathSelectors.any())
            .build()
            .operationCustomizer((operation, handlerMethod) -> {
                // 检查当前方法是否带有自定义注解
                if (handlerMethod.hasMethodAnnotation(Shared401Response.class)) {
                    // 将401响应合并到方法已有的响应列表中
                    operation.responseMessages(Stream.concat(
                            operation.getResponseMessages().stream(),
                            Stream.of(new ResponseMessageBuilder()
                                    .code(401)
                                    .message("Unauthorized - 需要身份验证")
                                    .responseModel(new ModelRef("ErrorResponse")) // 替换成你的错误响应模型
                                    .build())
                    ).collect(Collectors.toSet()));
                }
                return operation;
            });
}

步骤3：标记需要共享响应的方法 #

在控制器的第二个POST和DELETE方法上添加自定义注解，第一个POST方法保持原样即可：

@RestController
@RequestMapping("/api")
public class MyController {

    // 第一个POST方法：不需要401响应，不添加注解
    @PostMapping("/first")
    public ResponseEntity<String> firstPost() {
        return ResponseEntity.ok("First POST");
    }

    // 第二个POST方法：添加共享401响应
    @PostMapping("/second")
    @Shared401Response
    public ResponseEntity<String> secondPost() {
        return ResponseEntity.ok("Second POST");
    }

    // DELETE方法：添加共享401响应
    @DeleteMapping("/item/{id}")
    @Shared401Response
    public ResponseEntity<Void> deleteItem(@PathVariable Long id) {
        return ResponseEntity.noContent().build();
    }
}

方案二：拆分Docket分组 #

如果不喜欢用注解，也可以通过创建多个Docket实例，分别对应不同的端点分组，只为目标分组添加全局401响应。

配置多个Docket #

// 第一个Docket：仅包含第一个POST方法，不添加401响应
@Bean
public Docket firstPostApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("first-post-api")
            .select()
            .apis(RequestHandlerSelectors.methodsMatchers(HttpMethod.POST))
            .paths(PathSelectors.ant("/api/first"))
            .build();
}

// 第二个Docket：包含第二个POST和DELETE方法，添加全局401响应
@Bean
public Docket sharedResponseApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("shared-responses-api")
            .select()
            .apis(RequestHandlerSelectors.basePackage("你的控制器所在包路径"))
            .paths(PathSelectors.or(
                    PathSelectors.ant("/api/second"),
                    PathSelectors.ant("/api/item/**")
            ))
            .build()
            // 为POST方法添加全局401响应
            .globalResponseMessage(HttpMethod.POST, Collections.singletonList(
                    new ResponseMessageBuilder()
                            .code(401)
                            .message("Unauthorized - 需要身份验证")
                            .responseModel(new ModelRef("ErrorResponse"))
                            .build()
            ))
            // 为DELETE方法添加全局401响应
            .globalResponseMessage(HttpMethod.DELETE, Collections.singletonList(
                    new ResponseMessageBuilder()
                            .code(401)
                            .message("Unauthorized - 需要身份验证")
                            .responseModel(new ModelRef("ErrorResponse"))
                            .build()
            ));
}

注意事项 #

之前你尝试多个Docket没生效，大概率是路径匹配规则没写对，要确保每个Docket的paths能精准匹配目标端点，避免交叉覆盖。

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