（文末有彩蛋，不看白不看）兑现一下之前答应读者的事

news2024/9/25 5:24:29

大家过年好呀！（我）明天就要开工上班啦！在假期的最后一天踢了会球，简单吃点东西，晚上来兑现答应一位读者的事情。开整！

前情提要

这篇文章缘起于「开发者」技术交流群中一位读者遇到的问题：

在这里插入图片描述

简单来说，就是 Spring Boot 3 + Swagger3 的组合用之前的方式配置有问题。趁着假期还在，咱们把问题解决了，也算是兑现之前的承诺。

问题重现

我们先来复现一下这位读者描述的问题，首先下载《Spring Boot趣味实战课》Swagger 章节的相关源码：

https://github.com/liushuijinger/spring-boot-book/tree/master/05-rest

然后将 Spring Boot 的版本升级到 3.0+。当然，在此之前，你需要先配置好 JDK 17 及以上的 Java 环境。

以上操作完成后，我们启动项目。这时你会看到类似如下的报错：

java.lang.TypeNotPresentException: Type javax.servlet.http.HttpServletRequest not present
  at java.base/sun.reflect.generics.factory.CoreReflectionFactory.makeNamedType(CoreReflectionFactory.java:117) ~[na:na]
  at java.base/sun.reflect.generics.visitor.Reifier.visitClassTypeSignature(Reifier.java:125) ~[na:na]
  at java.base/sun.reflect.generics.tree.ClassTypeSignature.accept(ClassTypeSignature.java:49) ~[na:na]
  ......
Caused by: java.lang.ClassNotFoundException: javax.servlet.http.HttpServletRequest
  at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641) ~[na:na]
  at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188) ~[na:na]
  at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520) ~[na:na]
  at java.base/java.lang.Class.forName0(Native Method) ~[na:na]
  at java.base/java.lang.Class.forName(Class.java:467) ~[na:na]
  at java.base/sun.reflect.generics.factory.CoreReflectionFactory.makeNamedType(CoreReflectionFactory.java:114) ~[na:na]
  ... 37 common frames omitted

Disconnected from the target VM, address: '127.0.0.1:59039', transport: 'socket'

Process finished with exit code 0

解决问题

《Spring Boot趣味实战课》中使用了 knife4j，所以我们直接基于 knife4j 进行配置。还是我们熟悉的步骤，先添加 Maven 依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

记得将之前与 Swagger 有关的依赖全部删除。

接下来修改 Swagger 的配置类：

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot趣味实战")
                        .version("1.0")
                        .description( "Spring Boot趣味实战的 RESTFul 接口文档说明")
                        .termsOfService("https://liushuijinger.blog.csdn.net")
                        .license(new License().name("Apache 2.0")
                                .url("https://liushuijinger.blog.csdn.net")));
    }

}

最后修改一下 Controller：

@RestController
@Tag(name = "Swagger Demo")
@RequestMapping("/rest")
public class RestFulController {
    
    @GetMapping("/swagger")
    @Operation(summary = "Swagger 接口")
    public String swagger() {
        return "Swagger Method";
    }
    
}

其实就是换了两个注解。

改完以后，我们启动项目并访问 http://localhost:8080/doc.html 来看看效果：

在这里插入图片描述

OK，看到这个界面，说明问题已经搞定了。那么这是怎么一回事呢？

收个尾

导致 Spring Boot 3 与之前的配置不兼容的原因很简单——Spring Boot 3 只支持 OpenAPI3 规范，需要引用 springdoc-openapi 相关的 Jar。所以，换掉 Maven 依赖，再简单修改一下，就 OK 了。

想知道具体是哪些依赖，或者想使用原生 Swagger 的可以戳这里：https://springdoc.org/

一些注解的变化：

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")