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

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

快捷目录

1.引言2.添加依赖3.配置类4.Java代码实现5.启动应用6.总结

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 {    @Bean    public 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();    //分组    @Bean    public GroupedOpenApi publicApi() {        return GroupedOpenApi.builder()                .group("api")                .pathsToMatch("/api/**")                .build();    }    @Bean    public GroupedOpenApi adminApi() {        return GroupedOpenApi.builder()                .group("admin")                .pathsToMatch("/admin/**")                .build();    }}

然后其他服务实现

@Profile({"dev", "test"})@Configurationpublic class SwaggerConfig extends SwaggerConf {    @Override    public 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的应用与差异
下一篇：随手记录第十五话 – Spring Boot 3.2.3+Grafana+Prometheus+Loki实现一套轻量级监控加日志收集系统

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