随手记录第十四话 -- 在 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 {


    @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"})
@Configuration
public 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实现一套轻量级监控加日志收集系统

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

相关推荐
Resean022312 小时前
Spring 源码分析(七)AOP 原理(上):代理的创建
java·后端·spring
Tangq一定可以的12 小时前
Spring AI Advisor 详解 - 给大模型调用加上“切面“,日志/过滤/记忆一键搞定
java·后端·spring
小巫编程室13 小时前
我造了一个 Java 能力包:让 AI 直接调用你的业务代码
java·前端·后端
雾隐隐o13 小时前
优搭校园 01|项目概览、技术选型与初始化
spring boot·mysql·vue
十有八七13 小时前
手搓 Agent(五):学会翻书——RAG,先查资料再回答
前端·人工智能·后端
Swot13 小时前
产品 RAG 知识库与 AI 顾问 设计与实现
前端·后端
深入云栈14 小时前
Netty 4.2.x 源码深度解析 (二十四):池化内存分配 —— PoolArena、PoolChunk 与 PoolSubpage
java·后端·架构
ServBay14 小时前
PHP 8.6 最新发布:语法更新、实用函数与升级要点
后端·php
我不会起名字32215 小时前
Agent 总调错工具?MCP 接进 Go 后端的 4 个约束
后端·go·agent·mcp
考虑考虑15 小时前
git刷新远程分支列表
git·后端·gitlab