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

最新推荐文章于 2025-04-07 11:34:40 发布

it界的哈士奇

最新推荐文章于 2025-04-07 11:34:40 发布

阅读量4.5k

点赞数 3

分类专栏： Spring java 文章标签： OpenAPI3 SpringDoc SpringFox Swagger3

本文链接：https://blog.csdn.net/m0_47333020/article/details/109776819

版权

java 同时被 2 个专栏收录

34 篇文章

订阅专栏

Spring

17 篇文章

订阅专栏

转移原因

在学习使用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"));
    }