从SpringFox向SpringDoc转移（OpenAPI2向OpenAPI3转移）


转移原因

在学习使用spring集成swagger3时查阅文档发现
SpringFox未支持 OpenAPI3 标准，而是还在支持2017年就已经停止维护的OpenAPI2了
而搜遍全网写OpenAPI3的教程少的可怜
但还是找到了与之相关的文章
文章跳转
但没有关于权限验证的相关教程，答案还得去官网找
官网链接

转移步骤

  • 删除springfox和swagger 2依赖项。而是添加springdoc-openapi-ui依赖

在这里插入图片描述

  • 2.替换注解

在这里插入图片描述

  • 3.替换Docket

在这里插入图片描述

  • 添加OpenAPI类型的bean
    在这里插入图片描述
    前四步都是官网上代码的，没有什么难度,所以不贴代码
    上面的配置可以直接写在启动类里面
    也可以创建一个配置类专门写关于swagger的配置
    这里我用第二种
    在这里插入图片描述
    配置完这四步后

  • 还需要在application.yml配置文件里做一些关于springDoc的配置

在这里插入图片描述

1
2
3
4
5
6
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 #包扫描路径

启动服务，访问网址

1
http://localhost:18081/swagger-ui.html (按自己的配置写)

界面大概就这样
在这里插入图片描述
如果访问后台接口不需要权限认证
那到这里就可以了
如果需要权限认证
那继续往后配

添加权限认证

我这里的后台接口访问都需要携带token请求头才允许访问
所以我选择使用一个全局安全认证
在官方文档里有这样一段相关的描述
在这里插入图片描述
试着把之前定义的OpenAPI修改

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@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代码有关系的
在这里插入图片描述
可以看出这里应该是能够对应上的
好在我又找到了一条文章链接介绍了相关字段的意义
添加链接描述
在这里插入图片描述
那接下来就能够配置了

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
  @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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
  @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"));
    }