如何在 Spring Boot 2.7 和 3.0 中使用 Swagger

参考链接：

快速创建 Spring Boot 项目模板：https://start.spring.io/

Spring Boot：https://github.com/spring-projects/spring-boot

Spring Boot 3.0 正式发布及新特性解读：https://www.cnblogs.com/jimmyhu/p/17300314.html

前言

最近研究了下如何在 Spring Boot 中使用 Swagger，发现在 Spring Boot 2.7 和 3.0 两个版本中的用法有所不同，特此记录。

省流助手

如果你只是想找一个能运行的最小 demo，请参考本人写的 demo 模板！！！

• Spring Boot 2.7 项目模板：https://github.com/CaoMeiYouRen/spring-boot-template

  • Java >= 1.8
  • Maven >= 3.6
  • Mysql >= 8.0

• Spring Boot 3.0 项目模板：https://github.com/CaoMeiYouRen/spring-boot-v3-template

  • Java >= 17
  • Maven >= 3.6
  • Mysql >= 8.0

如果你想了解更多细节，请继续往下看

在 Spring Boot 2.7 中使用 Swagger

1.环境要求

• Java >= 1.8
• Maven >= 3.6

1.1 修改项目的 Java 版本

如果你用的是 IDEA，请在项目上右键，点击打开模块设置，切换到项目设置，修改 Java SDK 为 1.8。

2.安装依赖

在 pox.xml 中添加如下依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.添加配置

新建一个配置文件，例如 Swagger2Config.java

@Configuration // 声明为配置文件，让spring加载
@EnableSwagger2 // 支持swagger2插件配置
public class Swagger2Config {
    @Bean
    public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return new BeanPostProcessor() {

            @Override
            public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
                if (bean instanceof WebMvcRequestHandlerProvider) {
                    customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
                }
                return bean;
            }

            private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
                List<T> copy = mappings.stream()
                        .filter(mapping -> mapping.getPatternParser() == null)
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }

            @SuppressWarnings("unchecked")
            private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
                try {
                    Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                    field.setAccessible(true);
                    return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
                } catch (IllegalArgumentException | IllegalAccessException e) {
                    throw new IllegalStateException(e);
                }
            }
        };
    }

    // apiInfo对象主要是设置我们api文档的标题，描述，访问的地址，创建者等信息
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("RESTful API")
                //版本号
                .version("1.0")
                //描述
                .description("RESTful API")
                .build();
    }

    // docket容器设置我们的文档基础信息，api包的位置，以及路径的匹配规则（包含四种：全匹配，不匹配，正则匹配和ant匹配）
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("ltd.cmyr")) // 这里请替换成自己的包名
                .paths(PathSelectors.any()).build();
    }
}

4.添加 Swagger 注解

package ltd.cmyr.demo.controller;


import io.swagger.annotations.ApiOperation;
import ltd.cmyr.demo.entity.ResponseData;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;

@RestController
public class DefaultController {

    @ApiOperation(value = "获取时间", httpMethod = "GET") // 在这里添加注解
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public Object time() {
        ResponseData data = new ResponseData(200, "OK", new Date());
        return new ResponseEntity<ResponseData>(data, HttpStatus.OK);
    }
}

5.运行项目

在 IDEA 中可通过如下方式运行

6.访问 Swagger 页面

默认情况下，访问http://127.0.0.1:8080/swagger-ui.html 即可看见 Swagger 页面

大功告成！

在 Spring Boot 3.0 中使用 Swagger

在 Spring Boot 3.0 中使用 Swagger 所需要的依赖和 2.7 有所不同。

原因很简单，Spring Boot 3.0 是一次大版本升级，故造成了很多不兼容更新。

例如最低兼容的 Java 版本为 17，底层也切换到了 Spring 6。

所以自 2020 年以来没有更新过的 springfox-swagger2 和 springfox-swagger-ui 自然不会兼容 2022 年发布的 Spring Boot 3.0。

所以，一个很简单的解决方法就是，换一个 Swagger 依赖不就行了？

1.环境要求

请注意，运行 Spring Boot 3.0 必须要 Java 17 及以上，所以请升级你的 Java 版本！

• Java >= 17

• Maven >= 3.6

1.1 修改项目的 Java 版本

如果你用的是 IDEA，请在项目上右键，点击打开模块设置，切换到项目设置，修改 Java SDK 为 17。

2.安装依赖

在 pox.xml 中添加如下依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

3.添加配置

springdoc-openapi-starter-webmvc-ui默认情况下即可直接运行，无需其他配置。

你可以在 application.yml 中添加如下配置来设置 swagger-ui 的路径。

更多配置请参考官网：https://springdoc.cn/spring-rest-openapi-documentation/

springdoc:
  swagger-ui:
    path: "/swagger-ui.html"

4.添加 Swagger 注解

由于更换了依赖，因此原先的注解自然也是不能用的，但实际上大同小异，写起来还是类似的。

参考代码如下：

package ltd.cmyr.demo.controller;


import io.swagger.v3.oas.annotations.Operation;
import ltd.cmyr.demo.entity.ResponseData;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;

@RestController
@RequestMapping("/")
public class DefaultController {

    @Operation(summary = "获取时间", method = "GET") // 在这里添加注解。可以看到注解由原来的 ApiOperation 更改为 Operation ，但实际上内容是一致的
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public Object time() {
        ResponseData data = new ResponseData(200, "OK", new Date());
        return new ResponseEntity<ResponseData>(data, HttpStatus.OK);
    }
}

5.运行项目

在 IDEA 中可通过如下方式运行

6.访问 Swagger 页面

默认情况下，访问http://127.0.0.1:8080/swagger-ui.html 即可看见 Swagger 页面。

由于版本差异，UI 看上去和之前的有些不一样，但功能上还是一样的，没什么区别

至此，我们完成了在 Spring Boot 3.0 中使用 Swagger 的配置！大功告成！

附加内容：如何选择 Spring Boot 版本

关于 Spring Boot 2.7 和 3.0 两个版本，我们该如何做出选择呢？

没图没真相，请看下图的数据。

数据源自：https://newrelic.com/resources/report/2023-state-of-the-java-ecosystem

在 2023 年，使用率最高的 Java 版本是 11，占比达 56.06%；其次是 Java8，占比 32.99%；然后才是 Java17。

虽然看上去 Java17 目前的使用率还不是很高，但参考 Java8 在短短 3 年内占比就大幅下滑的情况，未来，作为新的 LTS 版本的 Java17 使用率必然会迅速上升。

所以，如果你的项目是新项目，要在未来长期维护的，那么建议选择 Spring Boot 3.0，基于 Java17 进行开发；如果你的项目还需要向下兼容，主要考虑旧的逻辑，那么建议选择 Spring Boot 2.7 ，毕竟 Java8 的生态还是非常完备的，很多旧的依赖包也只支持 Java8。

总结

本文介绍了如何在如何在 Spring Boot 2.7 和 3.0 中使用 Swagger，读者可参考本文的内容按步骤进行配置 Swagger，并选择适合自己的 Spring Boot 版本。

• 本文作者： 草梅友仁(CaoMeiYouRen)
• 本文链接： https://wp.cmyr.ltd/archives/how-to-use-swagger-in-spring-boot-2-7-and-3-0
• 版权声明： 本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！