首页 > 软件编程 > java > SpringBoot3.x整合swagger

SpringBoot3.x整合swagger的实现示例

2025-08-05 10:18:40 作者：比晚风温柔

本文主要介绍了SpringBoot3.x整合swagger的实现示例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧

零、提示

由于SpringBoot以及swagger的版本更新迭代得都比较快，因此当你采用最新版SpringBoot时，最好也使用最新版的swagger依赖。依赖在下面的网址进行查找，输入对应的artifactId就可以找到了

https://mvnrepository.com/

一、简介

官网：https://swagger.io/

对于SpringBoot而言，Swagger的作用是通过后端SpringBoot代码快速生成接口文档，方便测试接口以及前端使用。

二、基本使用

由于springfox不适用于SpringBoot3.x，故使用Springdoc进行代替。

1. 引入依赖

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

2. 其它相关依赖

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>


		<!-- 让响应结果更美观 -->
		<dependency>
			<groupId>com.alibaba.cola</groupId>
			<artifactId>cola-component-dto</artifactId>
			<version>4.3.2</version>
		</dependency>

2. 编写配置文件

添加 swagger 的配置文件 SwaggerConfig.java

@Configuration
public class SwaggerConfig {

}

此时Swagger已经简单整合成功，运行SpringBoot服务，浏览器打开网址进行测试

http://localhost:8080/swagger-ui/index.html

我使用的是8081端口，因此我使用下面的链接打开

http://localhost:8081/swagger-ui/index.html

3. 配置Swagger文档基本信息

@Configuration
public class SwaggerConfig {
    /*
    配置swagger基本信息
     */
    @Bean
    public OpenAPI swaggerOpenApi() {
        return new OpenAPI()
                .info(new Info().title("Swagger学习-比晚风温柔")
                        .description("Swagger简单入门")
                        .version("v1.0"))
                .externalDocs(new ExternalDocumentation()
                        .description("我的博客")
                        .url("https://blog.csdn.net/2202_76007821?spm=1000.2115.3001.5343"));
    }
}

此时重新运行服务，打开网址

http://localhost:8081/swagger-ui/index.html

4. 控制 Swagger 的开启

在开发或者测试环境下，我们开启 swagger 会方便前端和后端的交互，但是如果在生产环境下也开启 swagger 的话，是会将接口暴露出去的，有极大风险，如何让 swagger 根据不同的环境来决定是否开启？

这里我准备了四个项目的配置文件，dev、prod 两个环境的配置文件仅是端口上的不同

application.yml -------------------------- 全局配置文件
application-dev.yml -------------------- 开发环境配置文件
application-prod.yml -------------------- 生产环境配置文件

application-dev.yml配置

springdoc:
  api-docs:
    enabled: true # 开启OpenApi接口
  swagger-ui:
    enabled: true # 开启swagger界面，依赖OpenApi，需要OpenApi同时开启

application-prod.yml配置

springdoc:
  api-docs:
    enabled: false # 关闭OpenApi接口
  swagger-ui:
    enabled: false # 关闭swagger界面

application.yml 内容如下，用于指定选择的环境：

spring:
  profiles:
    active: dev

在 application.yml 全局配置文件中环境指向 dev 时，是可以打开 swagger 的

如果我将 application.yml 全局配置文件中环境指向 prod 时，就不能打开 swagger 了

5. 完善Swagger文档

5.1 实体类添加Swagger注解

@Component
@Schema(title = "水果类")
public class Fruit {
    @Schema(title = "水果名称",example = "塔菲新式番茄",minLength = 1,maxLength = 100)
    private String name;
    @Schema(title = "水果数量",example = "520")
    private Integer num ;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getNum() {
        return num;
    }

    public void setNum(Integer num) {
        this.num = num;
    }
}

@Schema: Swagger文档的注解，用于说明类/字段

title: 类/字段说明
example: 示例，Swagger中会将这个字段作为示例
minLength/maxLength: 最小/最大长度，字段为String类型时生效(仅用于文档说明，不会抛出异常)

5.2 控制器注解解析

@RestController
@RequestMapping("/fruit")
@Tag(name = "水果控制器",description = "这是水果测试接口")
public class FruitController {
    @PostMapping("/add")
    @Operation(summary = "新增水果",description = "这是新增水果的方法")
    public String add(Fruit fruit) {
        return "新增成功";
    }
}

@Tag: 控制器说明
- name: 名称
- description: 描述说明

@Operation: 请求说明
- summary: 说明，Swagger页面在方法后面，不会被折叠
- descirption: 描述，会被折叠到方法说明中

配置之后，让我们打开网址查看一下

6. 接口调用

点击进行测试

测试成功

三、使用postman进行接口测试

1. 导入链接

回到文档头部，点击api-docs

复制链接

打开postman，点击import

选择第二个进行导入

baseurl问题使用环境进行统一修改即可，点击创建新环境

手动修改参数