SpringBoot集成springdoc
✨重磅！盹猫的个人小站正式上线啦～诚邀各位技术大佬前来探秘！✨
这里有：
- 硬核技术干货：编程技巧、开发经验、踩坑指南，带你解锁技术新姿势！
- 趣味开发日常：代码背后的脑洞故事、工具测评，让技术圈不再枯燥～
- 独家资源分享：开源项目、学习资料包，助你打怪升级快人一步！
👉 点击直达→ 盹猫猫的个人小站 👈
🌟 来逛逛吧，说不定能挖到你正在找的技术宝藏哦～
目录
🚩 前言
🌿 环境准备
🍃 版本
🍃 Pom依赖
👊 代码步骤
🌲 配置类
🌲 注解
🥥 接口
🥥 响应内容
🌲 实现效果
🥥 API属性配置
🥥 接口
🌲 疑问解答
⭐ 总结
欢迎来到 盹猫(>^ω^<)的博客
本篇文章主要介绍了
[SpringBoot集成springdoc]
❤博主广交技术好友，喜欢文章的可以关注一下❤
🚩 前言
在实际工作中，swagger的在线api文档是非常好用的，它可以通过一些简单的配置和注解让自己的应用程序携带一个可以被在线访问的文档，无论是对内和对外API分享（但集成时仍然可能遇到些版本问题）。
⭕ 本篇文章就对SpringBoot如何集成swagger生成在线的文档方法进行记录。
🌿 环境准备
🍃 版本
| 名称 | 版本 |
|---|---|
| JDK | 21 |
| SpringBoot | 3.5.6 |
| springdoc | 2.7.0 |
🍃 Pom依赖
<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.5.6</version>
</parent>
<properties><maven.compiler.source>21</maven.compiler.source><maven.compiler.target>21</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties>
<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><exclusions><exclusion><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-logging</artifactId></exclusion></exclusions></dependency>
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.7.0</versio>
</dependency>
</dependencies>⚠️ 注意: 这里3.5.6的SpringBoot版本需要使用2.7.0的springdoc，如果是较低的如3.2+ 的springboot版本需要使用2.6.0的版本。
👊 代码步骤
🌲 配置类
在引入pom依赖后一般都会有一个配置类，对整个文档的一些属性进行定义，包含文档标题和接口版本等（毕竟谁也不想访问文档后，都不知道这是个什么项目😂），这些信息会在访问的swagger接口文档上显示。
具体配置内容如下：
package com.nodcat.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class SpringDocConfig {/*** 配置 API 文档元信息*/@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI()// 文档基本信息.info(new Info().title("青岛森林防火综合管理平台 API") // 文档标题.description("平台提供的火情监测、应急指挥、用户管理等接口文档") // 文档描述.version("v1.0.0") // 接口版本// 联系人信息（可选）.contact(new Contact().name("技术支持").email("support@fireplatform.com").url("http://fireplatform.com"))// 许可证信息（可选）.license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0")));}
}🌲 注解
接口包含一些请求的参数和响应参数需要使用注解的方式进行标记，以使自己的可读性更好，必须让对接方知道
这个接口的用途，请求的参数是什么意思，响应的内容是什么意思
否则绝对容易挨揍！！绝对容易挨揍！！绝对容易挨揍！！
🥥 接口
@GetMapping("/list")@Operation(summary = "获取商家套餐列表")public Result list(@Parameter(description = "分页", required = true)@RequestParam(value = "page", required = true)Integer page) {//已创建的套餐列表return Result.success("套餐列表");}在接口方法中可以使用@Operation注解对接口的名称进行配置，在请求参数中可以使用@Parameter注解对请求参数进行注释配置。
🥥 响应内容
package com.nodcat.common.json;import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;import java.io.Serializable;/*** 响应结果类:统一响应格式* @author nodcat*/
@Data
@Schema(description = "响应结果类")
public class Result implements Serializable {/*** 变量:{@param flag} [结果标签] 类型 {@link Boolean}* 枚举: true 成功 false 失败*/@Schema(description = "结果标签", example = "例如:true 成功 false 失败")private Boolean flag;/*** 变量:{@param code} [结果码] 类型 {@link Integer}* 枚举:200 成功 500失败*/@Schema(description = "结果码")private Integer code;/*** 变量:{@param msg} [提示信息] 类型 {@link String}* 枚举:*/@Schema(description = "提示信息")private String msg;/*** 变量:{@param data} [携带data数据] 类型 {@link Object}* 枚举:*/@Schema(description = "携带data数据")private Object data;public Result(Boolean flag, Integer code, String msg, Object data) {this.flag = flag;this.code = code;this.msg = msg;this.data = data;}/*** 响应成功(带返回数据)** @param data 返回数据* @return Result*/public static Result success(Object data) {return new Result(true, 200, "响应成功", data);}/*** 响应成功(带返回数据)** @param data 返回数据* msg 响应信息* @return Result*/public static Result success(Object data, String msg) {return new Result(true, 200, msg, data);}/*** 响应成功** @return Result*/public static Result success() {return new Result(true, 200, "响应成功", null);}/*** 响应错误(不带状态码,带消息)** @return Result*/public static Result error(String msg) {return new Result(false, 500, msg, null);}/*** 响应错误(带错误码,消息提醒)** @return*/public static Result errorMsg(Integer code, String msg) {return new Result(false, code, msg, null);}}在响应的内容中可以使用@Schema注解对响应的类和变量进行注解，这样在文章中就可以查看响应结果的中文注释了。
🌲 实现效果
默认请求地址：http://127.0.0.1:8080/swagger-ui/index.html
🥥 API属性配置
🥥 接口
🌲 疑问解答
🤔 当使用2.6.0的SpringDoc版本进行依赖会产生什么效果？
📢 当使用2.6.0的依赖版本时，会报错
'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'表示缺少这个类，必须使用2.7.0才能正常显示在线文档。
错误效果：
⭐ 总结
在SpringBoot3.5.6中可以使用springdoc的2.7.0快速创建在线的swagger文档，通过使用配置类，并配置【@Operation，@Schema，@Parameter】可以实现不错的API文档展示效果，文档还支持在线测试哦，快去试一试吧！
上面就是所有文章内容了,如果内容对你有帮助,麻烦留一个赞👍和收藏⭐支持一下!
如果你对区块链内容感兴趣可以查看我的专栏:小试牛刀-区块链
感谢您的关注和收藏!!!!!!
