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

参考链接：

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

Spring Boot：github.com/spring-proj…

Spring Boot 3.0 正式发布及新特性解读：www.cnblogs.com/jimmyhu/p/1…

前言

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

省流助手

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

• Spring Boot 2.7 项目模板：github.com/CaoMeiYouRe…

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

• Spring Boot 3.0 项目模板：github.com/CaoMeiYouRe…

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

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

在 Spring Boot 2.7 中使用 Swagger

1.环境要求

• Java >= 1.8
• Maven >= 3.6

2.安装依赖

在 pox.xml 中添加如下依赖

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

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  void customizeSpringfoxHandlerMappings(List mappings) {
                List copy = mappings.stream()
                        .filter(mapping -> mapping.getPatternParser() == null)
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }

            @SuppressWarnings("unchecked")
            private List getHandlerMappings(Object bean) {
                try {
                    Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                    field.setAccessible(true);
                    return (List) 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(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

2.安装依赖

在 pox.xml 中添加如下依赖

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.2.0

3.添加配置

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

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

更多配置请参考官网：springdoc.cn/spring-rest…

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(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 2.7 和 3.0 中使用 Swagger，读者可参考本文的内容按步骤进行配置 Swagger。

本文作者：草梅友仁

本文地址：blog.cmyr.ltd/archives/5c…

版权声明：转载请注明出处！