Spring-Boot 使用 Swagger-UI 时隐藏自动注入的实体类，并显示 HttpHeader 中的 token 参数

通常在构建 API 时会通过 在 HttpHeader 中传递 Token 参数来自动注入用户实体类，但是在 Swagger-UI 生成的文档中测试时，既没有输入 token 的地方，在参数列表中还存在用户实体类参数，造成了 Swagger-UI 与实际调用参数完全不符的情况。实际上使用一些简单的设置即可。

1. 显示 HttpHeader 中的 Token 参数

只需要在需要传递 token 的方法上添加一行注解

@ApiImplicitParams({@ApiImplicitParam(name = "ACCESS_TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

其中 ACCESS_TOKEN 为在 HttpHeader 中 token 的参数名，详细实例如下

@ApiOperation(value = "新增", notes = "新增一条广告")
@ApiImplicitParams({@ApiImplicitParam(name = "ACCESS_TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})
@RequestMapping(value = "/add", method = RequestMethod.POST)
public ExeResult addAd(@RequestBody @Validated AdAddReq req, @CurrentUser UserInfo userInfo) {
    return ExeResult.getInstance(adService.addAd(req.getTitle(), req.getDescription(), userInfo));
}

2. 隐藏自动注入的用户实体类

只需要在开启 Swagger 的方法中，设置 .ignoredParameterTypes() 方法，具体如下

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yulaiz.dong.web"))
                .paths(PathSelectors.any())
                .build()
                .ignoredParameterTypes(CurrentUser.class)
                .ignoredParameterTypes(CurrentToken.class);
    }
}

现在重新启动项目，打开 Swagger-UI 就都是按照实际情况的参数了。

3. 全局显示 HttpHeader 中的 Token 参数

2018-3-19 更新

在之前显示 Token 参数时，需要在每个 Controller 方法中新增 ApiImplicitParams 注解，这种方式有点就是可以指定哪些方法不需要显示，哪些方法需要显示，Swagger UI 也提供了一种方法，不需要每个方法上都手动标记，只需要在新建 Docket 的时候增加 globalOperationParameters 即可。

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        List<Parameter> list = Arrays.asList(
                new ParameterBuilder()
                        .name("ACCESS_TOKEN")
                        .description("Authorization token")
                        .modelRef(new ModelRef("string"))
                        .parameterType("header")
                        .build()
        );
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .globalOperationParameters(list)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yulaiz.dong.web"))
                .paths(PathSelectors.any())
                .build()
                .ignoredParameterTypes(CurrentUser.class)
                .ignoredParameterTypes(CurrentToken.class);
    }
}