Spring boot 2.0 升级到 3.3.1 的相关问题 （三）

Spring boot 2.0 升级到 3.3.1 的相关问题 （三）

Swagger 2 升级到 Springdoc-openapi 2.6.0

必须要升级，老的swagger使用的servlet-api，在JDK21的环境下已经不支持，启动会报错。java.lang.TypeNotPresentException: Type javax.servlet.http.HttpServletRequest not present

问题介绍

1、注解变动的问题。
原来的注解全部废弃了，需要全部使用新的注解。
2、配置变动的问题。
原来的配置方式全部失效，需要使用新的配置方式
3、项目中的注解如何批量迁移的问题。
编写工具，对所有的代码进行注解的转换。

解决方案

参考官方资料：https://springdoc.org/#migrating-from-springfox

废弃之前的所有swagger相关的依赖，改为引入springdoc-openapi-starter-webmvc-ui 依赖

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

注意不要参考网上的其他例子引入springdoc-openapi-ui 这个依赖。

配置变动

原配置

//@Configuration
//@EnableSwagger2
@Slf4j
public class Swagger2Config {@Value(value = "${spring.profiles.active}")String environment;@Value(value = "${spring.application.name}")String applicationName;@Value(value = "${spring.application.version}")String applicationVersion;@Value(value = "${spring.application.controller.packages}")String[] controllerPackages;String applicationDescription;@Value(value = "${spring.application.description}")private void setApplicationDescription(String applicationDescription) {this.applicationDescription = "";if (StringUtils.isBlank(applicationDescription)) {return;}byte[] data = applicationDescription.getBytes(StandardCharsets.ISO_8859_1);this.applicationDescription = new String(data, StandardCharsets.UTF_8);}/*** 业务系统的固定请求头*/public List<RequestParameter> getTokenPar() {RequestParameterBuilder tokenPar = new RequestParameterBuilder();List<RequestParameter> pars = new ArrayList<>();tokenPar.name(FrameConstant.HTTP_HEADER_AUTHORIZATION).description("认证信息").in(ParameterType.HEADER).required(true).build();pars.add(tokenPar.build());RequestParameterBuilder clientTypePar = new RequestParameterBuilder();clientTypePar.name(FrameConstant.HTTP_HEADER_CLIENT_TYPE).description("客户端版本类型").in(ParameterType.HEADER).required(true).build();pars.add(clientTypePar.build());RequestParameterBuilder clientVersionPar = new RequestParameterBuilder();clientVersionPar.name(FrameConstant.HTTP_HEADER_CLIENT_VERSION).description("客户端版本号").in(ParameterType.HEADER).required(true).build();pars.add(clientVersionPar.build());return pars;}@Beanpublic Docket createRestApi() {ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2).enable(("dev".equals(environment) || "test".equals(environment))).apiInfo(apiInfo()).globalRequestParameters(getTokenPar()).select();if(controllerPackages!=null && controllerPackages.length >0){Stream.of(controllerPackages).map(RequestHandlerSelectors::basePackage).forEach(builder::apis);}Docket api = builder.paths(PathSelectors.any()).build();String serverServletContextPath = SpringContextUtil.getApplicationContext().getEnvironment().getProperty("server.servlet.context-path");if(StringUtils.isNotBlank(serverServletContextPath)){api.pathMapping(serverServletContextPath+"/");}return api;}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(applicationName).description(applicationDescription).termsOfServiceUrl("http://").version(applicationVersion).build();}
}

新配置

/*** SpringDoc的配置*/
@Configuration @Slf4j public class SpringDocConfig {@Value(value = "${spring.application.name}") String applicationName;@Value(value = "${spring.application.version}") String applicationVersion;@Value(value = "${spring.application.controller.packages}") String[] controllerPackages;String applicationDescription;@Value(value = "${spring.application.description}")private void setApplicationDescription(String applicationDescription) {this.applicationDescription = "";if (StringUtils.isBlank(applicationDescription)) {return;}byte[] data = applicationDescription.getBytes(StandardCharsets.ISO_8859_1);this.applicationDescription = new String(data, StandardCharsets.UTF_8);}//    @Bean//    @Profile("!prod")//    public OpenAPI customOpenAPI() {//        return new OpenAPI()//            .components(new Components()//                .addHeaders(FrameConstant.HTTP_HEADER_AUTHORIZATION, new Header().required(true).description("认证信息"))//                .addHeaders(FrameConstant.HTTP_HEADER_CLIENT_TYPE, new Header().required(true).description("客户端版本类型"))//                .addHeaders(FrameConstant.HTTP_HEADER_CLIENT_VERSION, new Header().required(true).description("客户端版本号"))//            )//            .info(new Info()//                .title(applicationName)//                .description(applicationDescription)//                .termsOfService("http://")//                .version(applicationVersion));////    }@Bean @Profile("!prod") public GroupedOpenApi customOpenAPI() {return GroupedOpenApi.builder().group(applicationName).packagesToScan(controllerPackages).addOperationCustomizer((operation, handlerMethod) -> {operation.addParametersItem(new HeaderParameter().name(FrameConstant.HTTP_HEADER_AUTHORIZATION).description("认证信息").required(true));operation.addParametersItem(new HeaderParameter().name(FrameConstant.HTTP_HEADER_CLIENT_TYPE).description("客户端版本类型").required(true));operation.addParametersItem(new HeaderParameter().name(FrameConstant.HTTP_HEADER_CLIENT_VERSION).description("客户端版本号").required(true));return operation;}).addOpenApiCustomizer(openApi -> openApi.info(new Info().title(applicationName).description(applicationDescription).version(applicationVersion))).build();}}

注释掉的代码的方式也是可以的

批量注解转换工具

编写了一个独立的工具，使用JavaParser 来完成解析Java代码并修改更新Java的处理。最终将所有使用swagge2的注解的代码转换为SpringDoc的注解。

开源项目地址：https://gitcode.net/qiutongcunyi/swagger2springdoc-converter

该项目目前只做了我这边项目使用的一些注解的转换，如果你们有其他的注解需要转换，那么直接在这个项目基础上修改就可以了。

相关资料

SpringDoc官方文档：https://springdoc.org/#Introduction