转移原因
在学习使用spring集成swagger3时查阅文档发现
SpringFox未支持 OpenAPI3 标准,而是还在支持2017年就已经停止维护的OpenAPI2了
而搜遍全网写OpenAPI3的教程少的可怜
但还是找到了与之相关的文章
文章跳转
但没有关于权限验证的相关教程,答案还得去官网找
官网链接
转移步骤
- 删除springfox和swagger 2依赖项。而是添加springdoc-openapi-ui依赖
- 2.替换注解
- 3.替换Docket
-
添加OpenAPI类型的bean
前四步都是官网上代码的,没有什么难度,所以不贴代码
上面的配置可以直接写在启动类里面
也可以创建一个配置类专门写关于swagger的配置
这里我用第二种
配置完这四步后 -
还需要在application.yml配置文件里做一些关于springDoc的配置
springdoc:
swagger-ui:
path: /swagger-ui.html #swagger-ui访问路径 http://ip:端口/swagger-ui.html 默认就是swagger-ui.html
csrf:
enabled: true # 启用CSRF支持
packages-to-scan: com.xiaohong.user.controller #包扫描路径
启动服务,访问网址
http://localhost:18081/swagger-ui.html (按自己的配置写)
界面大概就这样
如果访问后台接口不需要权限认证
那到这里就可以了
如果需要权限认证
那继续往后配
添加权限认证
我这里的后台接口访问都需要携带token请求头才允许访问
所以我选择使用一个全局安全认证
在官方文档里有这样一段相关的描述
试着把之前定义的OpenAPI修改
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.components(new Components()
.addSecuritySchemes("basicScheme", new SecurityScheme()
.type(SecurityScheme.Type.HTTP).scheme("basic")))
.info(new Info().title("用户微服务")
.description("用户微服务接口文档")
.version("v0.0.1")
.license(new License().name("name").url("http://www.baidu.com")))
.externalDocs(new ExternalDocumentation()
.description("SpringShop Wiki Documentation")
.url("https://springshop.wiki.github.org/docs"));
}
重启服务
可以发现多了一个Authorize按钮
点开发现需要输入用户名和密码
这不是我想要的认证方式
我想要的是输入一段token
然后每次请求都把这段token 放到请求头中访问后台资源
那如何在请求头里添加参数呢?再次查看官方文档
找到相关的回答
点开链接看看
链接
可以看到这里有多种认证模式
刚刚使用的只是其中的HTTP模式
而根据文档
适合我的是API keys模式
那什么是API keys模式呢?点进去看一下
可以看到这种认证模式可以将token数据在请求时放到请求参数/请求头/cookie中
那怎么配置呢?继续往下看
这里给了一段示例代码
这不是Java格式,应该是json格式
仔细看还是能发现和之前的Java代码有关系的
可以看出这里应该是能够对应上的
好在我又找到了一条文章链接介绍了相关字段的意义
添加链接描述
那接下来就能够配置了
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.components(new Components().addSecuritySchemes("Authorization", // key值
new SecurityScheme()
.type(SecurityScheme.Type.APIKEY) //请求认证类型
.name("Authorization") //API key参数名
.description("token令牌") //API key描述
.in(SecurityScheme.In.HEADER))) //设置API key的存放位置
.info(new Info().title("用户微服务")
.description("用户微服务接口文档")
.version("v0.0.1")
.license(new License().name("name").url("http://www.baidu.com")))
.externalDocs(new ExternalDocumentation()
.description("SpringShop Wiki Documentation")
.url("https://springshop.wiki.github.org/docs"));
}
重启试试
感觉没问题
随便输入一个value试试,看看发送的请求里是否携带了请求头
没找到期待的请求头
那。。。继续看文档
发现我忽略了一小段配置
文档页写明了
仅配置securitySchemes是不够的,还需要使用security才能生效!!
那就添加一个security试试
发现需要一个参数
看源码
直接new一个试试
发现是接口。。
那就自己创一个!!
看不懂就全靠猜!!
再把list加进去
重启试试
幸福来得太突然哈哈哈
附上完整OpenAPI
@Bean
public OpenAPI springShopOpenAPI() {
SecurityRequirement securityRequirement = new SecurityRequirement().addList("Authorization"); // 名字和创建的SecuritySchemes一致
List<SecurityRequirement> list = new ArrayList<>();
list.add(securityRequirement);
return new OpenAPI()
.components(new Components().addSecuritySchemes("Authorization", // key值
new SecurityScheme()
.type(SecurityScheme.Type.APIKEY) //请求认证类型
.name("Authorization") //API key参数名
.description("token令牌") //API key描述
.in(SecurityScheme.In.HEADER))) //设置API key的存放位置
.security(list)
.info(new Info().title("用户微服务")
.description("用户微服务接口文档")
.version("v0.0.1")
.license(new License().name("name").url("http://www.baidu.com")))
.externalDocs(new ExternalDocumentation()
.description("SpringShop Wiki Documentation")
.url("https://springshop.wiki.github.org/docs"));
}
修正
这里请求头里没有传入数据是因为在api上少量一个配置
这里的name就是这里的key值
每个接口上的name值可以不一样,只要在配置文件里配置了即可
更全内容看
这里