SpringBoot3.x整合swagger的实现示例_Java

零、提示

由于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问题使用环境进行统一修改即可，点击创建新环境

手动修改参数

点击进行测试

四、代码

代码已经上传到gitee，打开网址，点击下载zip即可

https://gitee.com/guirongyuan/swagger-leaning

到此这篇关于springboot3.x整合swagger的实现示例的文章就介绍到这了,更多相关springboot3.x整合swagger内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！

SpringBoot3.x整合swagger的实现示例

2025年08月05日 • Java •我要评论