SpringBoot 3.x 结合 Swagger3 （Knife4j ）踩坑实录

悠扬随风  金牌会员 | 2024-6-22 13:36:04 | 显示全部楼层 | 阅读模式
打印 上一主题 下一主题
楼主

主题 850|帖子 850|积分 2550

SpringBoot 3.x + Swagger3 踩坑实录

我的是springboot 版本是：3.2.2
  1. <parent>
  2.         <groupId>org.springframework.boot</groupId>
  3.         <artifactId>spring-boot-starter-parent</artifactId>
  4.         <version>3.2.2</version>
  5.         <relativePath/>
  6.     </parent>
复制代码
官方文档

官方文档（快速开始）：
1，快速开始 | Knife4j (xiaominfo.com)
https://doc.xiaominfo.com/docs/quick-start
官方文档（详细配置）：
2， 增强模式 | Knife4j (xiaominfo.com)
https://doc.xiaominfo.com/docs/features/enhance
3，版本参考
Knife4j版本参考 | Knife4j (xiaominfo.com)
如果自己springboot 是 2.X.X 的版本，可参考官方文档，进行差别的依赖配置
以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐：

Knife4j在之前的版本更新中，逐渐提供了一些服务端适配的增强特性功能。
但是开发者应该明白，不管是Swagger2规范还是OpenAPI3规范，Knife4j的最新版本的纯Ui版本，是可以适配Spring Boot所有版本的。
如果你不考虑使用Knife4j提供的服务端增强功能，引入Knife4j的纯Ui版本没有任何限制。只需要考虑差别的规范即可
其实大部门的报错一般都是依赖问题（比如依赖缺少，版本辩论，版本不合）
错误操纵

依赖

网上帖子一般说的结合 knife4j（Swagger3）, 添加的依赖一般都只有knife4j。 但是这个是不对的，依赖没有完全，并且就算配置好yaml ，启动访问也会出错。完整依赖可看下面精确部门。
  1.          <dependency>
  2.             <groupId>com.github.xiaoymin</groupId>
  3.             <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
  4.             <version>4.4.0</version>
  5.         </dependency>
复制代码
yaml 配置

改的地方为：packages-to-scan:  com.example.eip.controller（自己项目的controller 目录）
其他地方基本上不用改。
  1. springdoc:
  2.   swagger-ui:
  3.     path: /swagger-ui.html
  4.     tags-sorter: alpha
  5.     operations-sorter: alpha
  6.   api-docs:
  7.     path: /v3/api-docs
  8.   group-configs:
  9.     - group: 'default'
  10.       paths-to-match: '/**'
  11.       #生成文档所需的扫包路径，一般为启动类目录
  12.       packages-to-scan: com.example.eip.controller
  15. #knife4j配置
  16. knife4j:
  17.   #是否启用增强设置
  18.   enable: true
  19.   #开启生产环境屏蔽
  20.   production: false
  21.   #是否启用登录认证
  22.   basic:
  23.     enable: true
  24.     username: admin
  25.     password: 123456
  26.   setting:
  27.     language: zh_cn
  28.     enable-version: true
  29.     enable-swagger-models: true
  30.     swagger-model-name: 用户模块
复制代码
这个时候访问是会报错：http://localhost:8069/doc.html#/home
报错信息解决


报错信息一： void io.swagger.v3.oas.models.OpenAPI.(io.swagger.v3.oas.models.SpecVersion)
这个报错才是访问不到的根本原因
原因：
  1. jakarta.servlet.ServletException: Handler dispatch failed: java.lang.NoSuchMethodError: 'void io.swagger.v3.oas.models.OpenAPI.<init>(io.swagger.v3.oas.models.SpecVersion)'
  2.         at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1104)
  3.         at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:979)
  4.         at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1014)
复制代码
报错信息二：No static resource favicon.ico  这个报错影响使用访问doc文档，但是不好看
原因：spring boot3项目中浏览器中访问报错找不到favicon.ico
目前springfox已经停止维护了。最近在升级底层框架时看到spring官方推荐使用springdoc，
这个情况有人去Github提了issue，但是Spring开发老哥说了这个不是bug，那就只能自己解决了。
  1. org.springframework.web.servlet.resource.NoResourceFoundException: No static resource favicon.ico.
  2.         at org.springframework.web.servlet.resource.ResourceHttpRequestHandler.handleRequest(ResourceHttpRequestHandler.java:585)
  3.         at org.springframework.web.servlet.mvc.HttpRequestHandlerAdapter.handle(HttpRequestHandlerAdapter.java:52)
  4.         at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1089)
  5.         at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:979)
  6.         at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1014)
  7.         at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:903)
  8.         at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:564)
  9.         at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:885)
  10.         at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:658)
  11.         at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:205)
复制代码
精确流程

这里先提供一下目录文件：

添加精确依赖

完整的添加所有的依赖，每个依赖都不能少，少就可能出错（可解决报错一）
  1.                     io.swagger.core.v3            swagger-core            2.2.20                        <dependency>
  2.             <groupId>com.github.xiaoymin</groupId>
  3.             <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
  4.             <version>4.4.0</version>
  5.         </dependency>                            org.springdoc            springdoc-openapi-starter-webmvc-api            2.2.0                            org.springframework.boot            spring-boot-configuration-processor            true                                    com.fasterxml.jackson.module            jackson-module-jakarta-xmlbind-annotations            2.13.3                        javax.xml.bind        jaxb-api        2.4.0-b180830.0359        
复制代码
添加yaml 配置
  1. springdoc:
  2.   swagger-ui:
  3.     path: /swagger-ui.html
  4.     tags-sorter: alpha
  5.     operations-sorter: alpha
  6.   api-docs:
  7.     path: /v3/api-docs
  8.   group-configs:
  9.     - group: 'default'
  10.       paths-to-match: '/**'
  11.       #生成文档所需的扫包路径，一般为启动类目录
  12.       packages-to-scan: com.example.eip.controller
  15. #knife4j配置
  16. knife4j:
  17.   #是否启用增强设置
  18.   enable: true
  19.   #开启生产环境屏蔽
  20.   production: false
  21.   #是否启用登录认证
  22.   basic:
  23.     enable: true
  24.     username: admin
  25.     password: 123456
  26.   setting:
  27.     language: zh_cn
  28.     enable-version: true
  29.     enable-swagger-models: true
  30.     swagger-model-name: 用户模块
复制代码
配置过滤静态资源
  1. import jakarta.servlet.http.HttpServletRequest;
  2. import jakarta.servlet.http.HttpServletResponse;
  3. import org.springframework.boot.SpringBootConfiguration;
  4. import org.springframework.http.HttpStatus;
  5. import org.springframework.web.servlet.HandlerInterceptor;
  6. import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
  7. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
  9. /**
  10. * @Classname FaviconConfiguration
  11. * @Description 添加配置文件，处理favicon.ico请求
  12. * @Version 1.0.0
  13. * @Date 2024/6/11 13:39
  14. * @Created by Administrator
  15. */
  17. @SpringBootConfiguration
  18. public class FaviconConfiguration implements WebMvcConfigurer {
  20.     @Override
  21.     public void addInterceptors(InterceptorRegistry registry) {
  22.         registry.addInterceptor(new HandlerInterceptor() {
  23.             @Override
  24.             public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
  25.                 if (!"GET".equalsIgnoreCase(request.getMethod()) || !request.getRequestURI().toString().equals("/favicon.ico")) {
  26.                     return true;
  27.                 }
  28.                 response.setStatus(HttpStatus.NO_CONTENT.value()); // 设置状态码为204 No Content
  29.                 return false;
  30.             }
  31.         }).addPathPatterns("/**");
  32.     }
  34. }
复制代码
这个时候就可以访问到文档：http://localhost:8069/doc.html#/home
增强模式

编写配置文件

这个部门注意是提供一些项目信息或者个人的信息
  1. import io.swagger.v3.oas.models.OpenAPI;
  2. import io.swagger.v3.oas.models.ExternalDocumentation;
  3. import io.swagger.v3.oas.models.info.Contact;
  4. import io.swagger.v3.oas.models.info.Info;
  5. import io.swagger.v3.oas.models.info.License;
  6. import org.springframework.context.annotation.Bean;
  7. import org.springframework.context.annotation.Configuration;
  9. /**
  10. * @Classname SwaggerConfig
  11. * @Description TODO
  12. * @Version 1.0.0
  13. * @Date 2024/6/11 14:16
  14. * @Created by Administrator
  15. */
  18. @Configuration
  19. public class SwaggerConfig {
  20.     @Bean
  21.     public OpenAPI swaggerOpenAPI(){
  22.         return new OpenAPI()
  23.                 .info(new Info().title("标题")
  24.                         // 信息
  25.                         .contact(new Contact().name("作者").email("邮箱").url("地址"))
  26.                         // 简介
  27.                         .description("我的API文档")
  28.                         // 版本
  29.                         .version("v1")
  30.                         // 许可证
  31.                         .license(new License().name("Apache 2.0").url("http://springdoc.org")))
  32.                 .externalDocs(new ExternalDocumentation()
  33.                         .description("外部文档")
  34.                         .url("https://springshop.wiki.github.org/docs"));
  35.     }
  36. }
复制代码
配置后的结果：

配置启动链接接口地点

每次都要打开浏览器输入地点访问不友好，我们在启动类似进行地点配置
启动类上优化 或者 编写配置类
第一种方式： 编写配置类(推荐使用)
创建文件：DocumentationConfig
  1. import io.micrometer.common.util.StringUtils;
  2. import lombok.extern.slf4j.Slf4j;
  3. import org.springframework.context.annotation.Configuration;
  4. import org.springframework.core.env.Environment;
  6. import java.net.InetAddress;
  7. import java.net.UnknownHostException;
  9. /**
  10. * @Classname DocumentationConfig
  11. * @Description TODO
  12. * @Version 1.0.0
  13. * @Date 2024/6/11 15:28
  14. * @Created by Administrator
  15. */
  19. @Configuration
  20. @Slf4j
  21. public class DocumentationConfig {
  23.     public void logApplicationStartup(Environment env) {
  24.         String protocol = "http";
  25.         if (env.getProperty("server.ssl.key-store") != null) {
  26.             protocol = "https";
  27.         }
  28.         String serverPort = env.getProperty("server.port");
  29.         String contextPath = env.getProperty("server.servlet.context-path");
  30.         if (StringUtils.isBlank(contextPath)) {
  31.             contextPath = "/doc.html";
  32.         } else {
  33.             contextPath = contextPath + "/doc.html";
  34.         }
  35.         String hostAddress = "localhost";
  36.         try {
  37.             hostAddress = InetAddress.getLocalHost().getHostAddress();
  38.         } catch (UnknownHostException e) {
  39.             log.warn("The host name could not be determined, using `localhost` as fallback");
  40.         }
  41.         log.info("""
  42.                         ----------------------------------------------------------
  43.                         \t应用程序“{}”正在运行中......
  44.                         \t接口文档访问 URL:
  45.                         \t本地: \t\t{}://localhost:{}{}
  46.                         \t外部: \t{}://{}:{}{}
  47.                         \t配置文件: \t{}
  48.                         ----------------------------------------------------------""",
  49.                 env.getProperty("spring.application.name"),
  50.                 protocol,
  51.                 serverPort,
  52.                 contextPath,
  53.                 protocol,
  54.                 hostAddress,
  55.                 serverPort,
  56.                 contextPath,
  57.                 env.getActiveProfiles());
  58.     }
  59. }
复制代码
第二种方式：启动类上优化
  1. import io.micrometer.common.util.StringUtils;
  2. import lombok.extern.slf4j.Slf4j;
  3. import org.mybatis.spring.annotation.MapperScan;
  4. import org.springframework.boot.Banner;
  5. import org.springframework.boot.SpringApplication;
  6. import org.springframework.boot.autoconfigure.SpringBootApplication;
  7. import org.springframework.core.env.Environment;
  9. import java.net.InetAddress;
  10. import java.net.UnknownHostException;
  12. @SpringBootApplication
  13. @MapperScan("com.mijiu.mapper")
  14. @Slf4j
  15. public class SpringbootTemplateApplication {
  16.     public static void main(String[] args) {
  17.         SpringApplication app = new SpringApplication(SpringbootTemplateApplication.class);
  18.         Environment env = app.run(args).getEnvironment();
  19.         app.setBannerMode(Banner.Mode.CONSOLE);
  20.         logApplicationStartup(env);
  22.     }
  23.     private static void logApplicationStartup(Environment env) {
  24.         String protocol = "http";
  25.         if (env.getProperty("server.ssl.key-store") != null) {
  26.             protocol = "https";
  27.         }
  28.         String serverPort = env.getProperty("server.port");
  29.         String contextPath = env.getProperty("server.servlet.context-path");
  30.         if (StringUtils.isBlank(contextPath)) {
  31.             contextPath = "/doc.html";
  32.         } else {
  33.             contextPath = contextPath + "/doc.html";
  34.         }
  35.         String hostAddress = "localhost";
  36.         try {
  37.             hostAddress = InetAddress.getLocalHost().getHostAddress();
  38.         } catch (UnknownHostException e) {
  39.             log.warn("The host name could not be determined, using `localhost` as fallback");
  40.         }
  41.         log.info("""
  42.                         ----------------------------------------------------------
  43.                         \t应用程序“{}”正在运行中......
  44.                         \t接口文档访问 URL:
  45.                         \t本地: \t\t{}://localhost:{}{}
  46.                         \t外部: \t{}://{}:{}{}
  47.                         \t配置文件: \t{}
  48.                         ----------------------------------------------------------""",
  49.                 env.getProperty("spring.application.name"),
  50.                 protocol,
  51.                 serverPort,
  52.                 contextPath,
  53.                 protocol,
  54.                 hostAddress,
  55.                 serverPort,
  56.                 contextPath,
  57.                 env.getActiveProfiles());
  58.     }
  60. }
复制代码
配置后的结果：点击可以直接访问

如果代码写的有问题，欢迎各人评论交流，进行指点！！！
也希望各人点个关注哦~~~~~~~~

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。

本帖子中包含更多资源

您需要 登录 才可以下载或查看，没有账号？立即注册

x
回复

使用道具 举报

0 个回复

倒序浏览
返回列表

快速回复

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 or 立即注册

本版积分规则

悠扬随风

金牌会员
这个人很懒什么都没写!

楼主热帖

标签云

存储 挺好的 服务器
微信订阅号
微信服务号
微信客服
小程序
H5
关于我们 商务合作 网站地图
©Copyright 2022-2024 杭州祥升科技有限公司 版权所有 浙ICP备20004199号
快速回复 返回顶部 返回列表