如何使用Spring Fox 3实现部分API添加通用请求头

针对你的场景（18个API需要通用请求头，2个不需要），推荐两种实现方案，根据实际情况选择：

方案一：全局配置+排除注解（推荐，适配多数API需要的场景） #

步骤1：定义排除注解 #

创建一个自定义注解，标记不需要通用请求头的API方法：

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

步骤2：配置Swagger Docket #

在Swagger配置类中添加全局通用请求头，并通过插件移除标记了@NoCommonHeaders的API的通用头：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        // 构建通用请求头参数列表
        List<Parameter> commonHeaders = Arrays.asList(
                new ParameterBuilder()
                        .name("uuid")
                        .description("128 bit random universally unique identifier (UUID)")
                        .modelRef(new ModelRef("string"))
                        .parameterType("header")
                        .required(true)
                        .build(),
                new ParameterBuilder()
                        .name("channelId")
                        .description("Registered channel ID")
                        .modelRef(new ModelRef("string"))
                        .parameterType("header")
                        .required(true)
                        .build(),
                new ParameterBuilder()
                        .name("businessCode")
                        .description("Business code")
                        .modelRef(new ModelRef("string"))
                        .parameterType("header")
                        .required(true)
                        .build()
        );

        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.api.package")) // 替换为你的API所在包路径
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(commonHeaders)
                .plugins(new OperationBuilderPlugin() {
                    @Override
                    public void apply(OperationContext context) {
                        // 检查当前方法是否标记了排除注解，是则移除通用头参数
                        if (context.findAnnotation(NoCommonHeaders.class).isPresent()) {
                            context.operationBuilder().parameters(
                                    context.operationBuilder().getParameters().stream()
                                            .filter(param -> !Arrays.asList("uuid", "channelId", "businessCode").contains(param.getName()))
                                            .collect(Collectors.toList())
                            );
                        }
                    }

                    @Override
                    public boolean supports(DocumentationType documentationType) {
                        return documentationType == DocumentationType.OAS_30;
                    }
                });
    }
}

步骤3：标记不需要通用头的API #

在那2个不需要通用请求头的API方法上添加@NoCommonHeaders注解即可：

@RestController
@RequestMapping("/demo")
public class DemoController {

    // 该API会自动带上通用请求头
    @GetMapping("/with-headers")
    public String withHeaders() {
        return "This API requires common headers";
    }

    // 该API不会包含通用请求头
    @NoCommonHeaders
    @GetMapping("/without-headers")
    public String withoutHeaders() {
        return "This API doesn't need common headers";
    }
}

方案二：自定义注解标记需要通用头的API #

如果后续需求变化，也可以用这种方式，只给需要的API标记注解：

步骤1：定义需要通用头的注解 #

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

步骤2：配置Swagger Docket #

通过插件为标记了@RequireCommonHeaders的API添加通用请求头：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.api.package"))
                .paths(PathSelectors.any())
                .build()
                .plugins(new OperationBuilderPlugin() {
                    @Override
                    public void apply(OperationContext context) {
                        // 检查当前方法是否标记了需要通用头的注解，是则添加参数
                        if (context.findAnnotation(RequireCommonHeaders.class).isPresent()) {
                            List<Parameter> commonHeaders = Arrays.asList(
                                    new ParameterBuilder()
                                            .name("uuid")
                                            .description("128 bit random universally unique identifier (UUID)")
                                            .modelRef(new ModelRef("string"))
                                            .parameterType("header")
                                            .required(true)
                                            .build(),
                                    new ParameterBuilder()
                                            .name("channelId")
                                            .description("Registered channel ID")
                                            .modelRef(new ModelRef("string"))
                                            .parameterType("header")
                                            .required(true)
                                            .build(),
                                    new ParameterBuilder()
                                            .name("businessCode")
                                            .description("Business code")
                                            .modelRef(new ModelRef("string"))
                                            .parameterType("header")
                                            .required(true)
                                            .build()
                            );
                            // 合并原有参数和通用头参数
                            context.operationBuilder().parameters(Stream.concat(
                                    context.operationBuilder().getParameters().stream(),
                                    commonHeaders.stream()
                            ).collect(Collectors.toList()));
                        }
                    }

                    @Override
                    public boolean supports(DocumentationType documentationType) {
                        return documentationType == DocumentationType.OAS_30;
                    }
                });
    }
}

步骤3：标记需要通用头的API #

在18个需要通用请求头的API方法上添加@RequireCommonHeaders注解，剩下2个无需标记：

@RestController
@RequestMapping("/demo")
public class DemoController {

    // 该API会带上通用请求头
    @RequireCommonHeaders
    @GetMapping("/with-headers")
    public String withHeaders() {
        return "This API requires common headers";
    }

    // 该API不会包含通用请求头
    @GetMapping("/without-headers")
    public String withoutHeaders() {
        return "This API doesn't need common headers";
    }
}

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