Swagger3中配置全局token参数

配置代码

@Configuration
// @Profile()
public class SwaggerConfig {
    
    
    @Bean
    public OpenAPI springShopOpenAPI() {
    
    

        return new OpenAPI()
                .components(components())
                // 2. 再在这里添加上Swagger要使用的安全策略
                // addList()中写上对应的key
                .addSecurityItem(new SecurityRequirement().addList("tokenScheme"));
    }
    // 1. 先在组件中注册安全策略
    private Components components(){
    
    
        return new Components()
        		// 第一个参数是key值，后面是初始化一个安全策略的参数
                .addSecuritySchemes("tokenScheme", new SecurityScheme().type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.HEADER).name("token"));
    }
}

打开Swagger页面，效果如下：

右边多了一把锁的标志，点击就可以输出token值。

点击Authorize之后，发送的请求都会自动在请求头中加上字段为token，值为输入值。

参考连接：springdoc-openapi-ui添加一个JWT请求头参数以生成swagger

安全策略类型 SecurityScheme.Type

注意到初始化安全策略时Type可以选择多种：

上例使用的就是apiKey类型，指定apiKey的位置，就可以在每次发送请求时自动赋上该apiKey。

如上图，除此之外，类型还有http等等类型，其他类型由于笔者暂时还没有接触过，不做说明，但是这个http安全策略是什么呢？接下来一起来了解一下。

http安全策略

在http协议中，也定义了安全认证方式，只不过可能由于实践中使用很少，因此很少听过。

WWW-Authenticate字段

我们可以在响应中返回401Unauthorized 状态码，并返回WWW-Authenticate字段，以告诉客户端该接口需要权限认证才能访问，并且在WWW-Authenticate字段中指明相关信息，比如使用身份认证方案。

具体可以参考MDN文档：WWW-Authenticate。

常见的身份认证方案有Basic、Bearer等等，这里不做具体说明。

Authorization

相应的我们在请求中也有** Authorization**字段用以返回用户凭证。语法是：

Authorization: <auth-scheme> <authorization-parameters>

第一个参数指定使用的身份认证方案，第二个参数指定认证参数。

具体可以参考MDN文档：Authorization。

在Swagger中实践

综上如果我们要使用http安全策略可以在Swagger中如下配置：

private Components components(){
    
    
        return new Components()
                .addSecuritySchemes("tokenScheme", new SecurityScheme().type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.HEADER).name("token"))
                // type指定为http scheme中指定为bearer
                .addSecuritySchemes("httpTest", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer"));
    }

Swagger页面如下：

需要注意的是由于这里是http安全策略，它只会在请求头中带上Authorization字段。如果说我们的token认证是直接读取请求头中的自定义字段token的话，这样设置是无效的。