Swagger2 不完美解决非全局设置header

在项目开发过程中，使用Swagger2快速生成接口文档，甚至进行Rest接口测试非常普遍。在某些项目中，请求的Header中往往设置一些全局标识用于认证，但又有部分Rest接口不需要验证这个全局标识。而在进行Swagger2配置的时候，又只能设置全局header开关。

例如

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        
        ParameterBuilder aParameterBuilder = new ParameterBuilder();
        aParameterBuilder.name("openid").description("openid").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
        
        List<Parameter> aParameters = Lists.newArrayList();
        aParameters.add(aParameterBuilder.build());
        
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(aParameters)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sam.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

这时候所有的Rest接口均需要header中有openid这个参数，如果某几个Rest地址不需要呢？至少我没找到Swagger2中对特定Rest路径进行header设置的方法，网上大多数博文均提到采用Filter方式实现，个人觉得这样会增加维护的负担。

如果不是完美主义者，可以在Controller方法中通过设置非必填header类型参数以覆盖全局设置。

例如

@RestController
@RequestMapping(value="/error")
public class ErrorController extends BaseController {
    
    @RequestMapping(value="/404")
    @ApiImplicitParam(name = "openid", value = "openid", required = false, dataType = "String",paramType="header")
    public Object notFoundError(){
        JsonResult result = new JsonResult("404","无效请求地址");
        setReturnValMaskLogString(result);
        return result;
    }
    
    @RequestMapping(value="/500")
    @ApiImplicitParam(name = "openid", value = "openid", required = false, dataType = "String",paramType="header")
    public Object serverError(){
        JsonResult result = new JsonResult("500", "内部异常");
        setReturnValMaskLogString(result);
        return result;
    }
}

这时候Swagger页面还是会显示openid参数的输入框，

EBVJ2{6SV3)@ZVQ18@PGE)1.png

openid已不是必填项，虽影响美观，但也将就应付，毕竟不是核心功能。