去我的博客查看

網(wǎng)絡(luò)上關(guān)于Swagger2的教程多如牛毛，關(guān)于Swagger加入全局head參數(shù)（如token）的文章也很多。例如:

Swagger2 添加HTTP head參數(shù)

Swagger2 添加HTTP head參數(shù)，解決用戶是token信息保留

但上述方案存在2個(gè)不足之處：

1. 需要在每個(gè)接口下單獨(dú)輸入?yún)?shù)
2. 全局配置了參數(shù)，如果某些接口（如login等）不需要參數(shù)，則必須在改接口中通過annotation現(xiàn)實(shí)聲明，較為麻煩

綜上，選擇優(yōu)化方案如下：

1. 通過Swagger2的securitySchemes配置全局參數(shù)：如下列代碼所示，securitySchemes的ApiKey中增加一個(gè)名為“Authorization”，type為“header”的參數(shù)。

private List<ApiKey> securitySchemes() {
        return newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
 }

2. 在Swagger2的securityContexts中通過正則表達(dá)式，設(shè)置需要使用參數(shù)的接口（或者說，是去除掉不需要使用參數(shù)的接口），如下列代碼所示，通過PathSelectors.regex("^(?!auth).*$")，所有包含"auth"的接口不需要使用securitySchemes。即不需要使用上文中設(shè)置的名為“Authorization”，type為“header”的參數(shù)。

private List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build()
        );
    }

設(shè)置完成后進(jìn)入SwaggerUI，右上角出現(xiàn)“Authorization”按鈕，點(diǎn)擊即可輸入我們配置的參數(shù)。
對(duì)于不需要輸入?yún)?shù)的接口（上文所述的包含auth的接口），在未輸入Authorization參數(shù)就可以訪問。
其他接口則將返回401錯(cuò)誤。點(diǎn)擊右上角“Authorization”按鈕，輸入配置的參數(shù)后即可訪問。參數(shù)輸入后全局有效，無需每個(gè)接口單獨(dú)輸入。

image.png

至此，完成Swagger2 非全局、無需重復(fù)輸入的Head參數(shù)配置。
Swagger2的相關(guān)完整代碼如下（工程基于Springboot）：

@Configuration
@EnableSwagger2
public class Swagger {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).
                useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("^(?!auth).*$"))
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                ;
    }

    private List<ApiKey> securitySchemes() {
        return newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
    }

    private List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build()
        );
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
                new SecurityReference("Authorization", authorizationScopes));
    }
}

去我的博客查看