随手记录第十四话 -- 在 Spring Boot 3.2.3 中使用 springdoc-openapi-starter-webmvc-ui

项目升级到JDK21后，SpringBoot版本也到了3.2.3，之前的Swagger-ui不在支持了，找了其他的一直忘记记录了，这里记录一下。

1.引言

随着 Spring Boot 版本的更新，一些依赖和配置也发生了变化。在 Spring Boot 3.2.3 中，原来常用的 Swagger-UI 不再直接支持，我们需要切换到 springdoc-openapi-starter-webmvc-ui 来实现类似的 API 文档功能。

2.添加依赖

基于Springboot3.2.3，引入pom依赖

<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.3</version><relativePath/> <!-- lookup parent from repository -->
</parent><!-- Swagger UI 相关 -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version>
</dependency>

3.配置类

你可以创建一个配置类来进一步定制 OpenAPI 的相关属性，比如文档标题、版本等。

/*** 创建一个公共类* api页面 http://127.0.0.1:8080/swagger-ui/index.html*/
@SecurityScheme(name = "Authorization", type = SecuritySchemeType.HTTP, scheme = "bearer", in = SecuritySchemeIn.HEADER)
public abstract class SwaggerConf {@Beanpublic OpenAPI createOpenApi() {return new OpenAPI().info(apiInfo())//设置授权信息.security(List.of(new SecurityRequirement().addList("Authorization")))//引入其他文档
//                .externalDocs(new ExternalDocumentation().description("百度一下")
//                        .url("http://www.baido.com"));}public abstract Info apiInfo();//分组@Beanpublic GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("api").pathsToMatch("/api/**").build();}@Beanpublic GroupedOpenApi adminApi() {return GroupedOpenApi.builder().group("admin").pathsToMatch("/admin/**").build();}
}

然后其他服务实现

@Profile({"dev", "test"})
@Configuration
public class SwaggerConfig extends SwaggerConf {@Overridepublic Info apiInfo() {return new Info().title("一款 xxx 业务接口文档").description("xxx业务处理").version("1.0");}
}

4.Java代码实现

@Tag(name = "钱包app相关接口")
@RestController
@RequestMapping("/api/app")
public class WalletController {@Operation(summary = "获取钱包初始化配置", description = "获取配置")@AnonymousGetMapping("/homeConfig")public ApiResultVO<JSONObject> getHomeConfig(@RequestParam(required = false) Long fromId) {.....    }
}//返回bean注解
@NoArgsConstructor
@Data
@Schema(name = "ApiResult", description = "REST接口标准返回值 View Model")
public class ApiResultVO<T> implements Serializable {/*** 返回码*/@Schema(title ="REST接口返回码")private Integer code;/*** 返回描述*/@Schema(title ="REST接口返回消息")private String message;
}

如果需要使用鉴权头部，需要用下面这个注解

@SecurityScheme(name = "Authorization", type = SecuritySchemeType.HTTP, scheme = "bearer", in = SecuritySchemeIn.HEADER)

5.启动应用

地址与原来的有点区别 http://127.0.0.1:8080/swagger-ui/index.html

实体类截图

6.总结

通过使用 springdoc-openapi-starter-webmvc-ui ，我们可以在 Spring Boot 3.2.3 中继续方便地生成和展示 API 文档，帮助我们更好地理解和管理项目中的接口。在实际应用中，可以根据需要进行更深入的定制和优化。
希望这篇文章对你顺利过渡到新的 API 文档工具提供帮助，让你在开发过程中能够更好地与 API 进行交互和文档化。

上一篇：随手记录第十三话 – 关于Python自动化部署神器fabric的应用与差异
下一篇：随手记录第十五话 – xxxx

烹羊宰牛且为乐，会须一饮三百杯