Spring Boot微服务A集成Swagger2本地调试请求头报错咨询

我之前也碰到过几乎一模一样的场景——微服务A依赖微服务B的请求头Token做认证，集成Swagger2后本地UI根本跑不起来，因为请求过不了B的校验。下面几个方案亲测有效，你可以根据自己的场景选：

方案1：给Swagger配置全局默认请求头 #

最直接的办法就是让Swagger UI发起请求时自动带上Microservice-B要求的Token头。你只需要在Swagger的配置类里添加全局参数，填入一个从B那边获取到的测试用有效Token就行。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourteam.microservicea"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(Collections.singletonList(
                        new ParameterBuilder()
                                .name("Authorization") // 替换成Microservice-B要求的Token头名称
                                .description("Valid Token from Microservice-B")
                                .modelRef(new ModelRef("string"))
                                .parameterType("header")
                                .defaultValue("Bearer your-test-token-value") // 填入测试Token
                                .required(true)
                                .build()
                ));
    }
}

配置完之后，Swagger UI的所有请求都会自动带上这个头，本地测试时不用手动输入，直接就能调用接口。

方案2：开发环境下跳过B的认证（仅本地生效） #

如果你的项目区分开发/生产环境，更优雅的方式是在dev环境给A加个过滤器，当请求来自Swagger UI时自动注入合法Token，不用真的去调用B。这样既不影响生产环境的认证逻辑，又能方便本地调试。

示例过滤器代码：

@Component
@Profile("dev") // 只在开发环境启用
public class SwaggerTokenFilter extends OncePerRequestFilter {
    // 匹配Swagger相关的路径
    private static final List<String> SWAGGER_PATHS = Arrays.asList(
            "/swagger-ui.html",
            "/v2/api-docs",
            "/swagger-resources",
            "/webjars"
    );

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String requestUri = request.getRequestURI();
        boolean isSwaggerRequest = SWAGGER_PATHS.stream().anyMatch(requestUri::contains);
        
        if (isSwaggerRequest) {
            // 包装请求，添加Token头
            HttpServletRequest wrappedRequest = new HttpServletRequestWrapper(request) {
                @Override
                public String getHeader(String name) {
                    if ("Authorization".equals(name)) {
                        return "Bearer your-test-token-value";
                    }
                    return super.getHeader(name);
                }
            };
            filterChain.doFilter(wrappedRequest, response);
        } else {
            filterChain.doFilter(request, response);
        }
    }
}

方案3：本地搭建代理转发请求（严格模拟生产流程） #

如果必须严格模拟生产环境的请求链路（所有请求必须经过B），可以在本地用Spring Cloud Gateway或者Nginx搭个代理，把Swagger的请求先转发到B，再由B转发到A，同时在代理里自动添加Token头。

比如用Spring Cloud Gateway的配置（application.yml）：

spring:
  cloud:
    gateway:
      routes:
        - id: microservice-b-route
          uri: http://localhost:8080 # Microservice-B的本地端口
          predicates:
            - Path=/api/** # 匹配Microservice-A的接口路径
          filters:
            - AddRequestHeader=Authorization, Bearer your-test-token-value

之后你通过网关的端口访问Swagger UI，请求就会自动带上Token经过B的认证，再转发到A，完全模拟生产流程。

小提醒 #

不管用哪种方案，测试用的Token一定要确保在Microservice-B的开发环境是有效的，最好找负责B的团队要一个长期有效的测试Token，避免频繁过期影响调试。

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