SpringBoot-集成Swagger

《一线大厂Java面试题解析+核心总结学习笔记+最新讲解视频+实战项目源码》，点击传送门，即可获取！

return “hello”;

}

}

浏览器：

正常运行！

4.使用Swagger，需要编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration //配置类

@EnableSwagger2// 开启Swagger2的自动配置

public class SwaggerConfig {

}

5.测试进入Sawgger页面

重启主程序，访问 localhost:8080/swagger-ui.html

发现启动报错：

原因：是因为我们的SpringBoot版本过高

org.springframework.boot

spring-boot-starter-parent

2.6.2

将其版本降低即可，改为2.5.4

org.springframework.boot

spring-boot-starter-parent

2.5.4

我们重启主程序，访问 localhost:8080/swagger-ui.html

出现以下页面说明访问成功了。

这个界面是Swagger为我们提供的ui界面，我们可以在源码中找到它

四、配置Swagger API信息

=================

（1)Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

@Bean //配置docket以配置Swagger具体参数

public Docket docket() {

return new Docket(DocumentationType.SWAGGER_2);

}

(2）通过apiInfo()属性配置文档信息

//配置文档信息

private ApiInfo apiInfo() {

Contact contact = new Contact(“联系人名字”, “http://xxx.xxx.com/联系人访问链接”, “联系人邮箱”);

return new ApiInfo(

“Swagger学习”, // 标题

“学习演示如何配置Swagger”, // 描述

“v1.0”, // 版本

“http://terms.service.url/组织链接”, // 组织链接

contact, // 联系人信息

“Apach 2.0 许可”, // 许可

“许可链接”, // 许可连接

new ArrayList<>()// 扩展

);

}

（3）Docket 实例关联上 apiInfo()

@Bean //配置docket以配置Swagger具体参数

public Docket docket() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo());//配置Swagger信息;

}

重启主程序测试，可以看到Swagger信息已经变更成我们定义的信息

五、配置Swagger自定义扫描接口

==================

5.1 默认状态

---

我们在这个ui界面中，可以看到扫描了两个controller接口；

一个是默认的/error请求，也就是我们启动springboot主程序未加配置默认访问8080端口的默认controller

另一个是我们自己写的/test请求，对应着MyController，由于我们用的@RequsetMapping注解，所以请求的方式有以上的六种

@RestController

public class MyController {

@RequestMapping(“/test”)

public String test(){

return “hello”;

}

}

5.2 配置扫描接口

---

（1）构建Docket时通过select()方法配置扫描接口。

@Bean

public Docket docket() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())//配置Swagger信息

.select()

/**

• apis():指定扫描的接口

• RequestHandlerSelectors:配置要扫描接口的方式

• basePackage:指定要扫描的包

• any:扫面全部

• none:不扫描

• withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)

• withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)

*/

.apis(RequestHandlerSelectors.basePackage(“com.yixin.demo.controller”)

.build();

}

(2) 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到自定义路径下的controller

5.3 配置接口扫描过滤

---

作用：再次过滤指定路径下的请求接口

例如：

配置如何通过path过滤,即这里只扫描请求以/yixin开头的接口

paths(PathSelectors.ant(“/yixin/**”))

实现测试：

（1）编写Controller

@RestController

public class MyController {

@RequestMapping(“/test”)

public String test(){

return “hello”;

}

@RequestMapping(“/yixin/test”)

public String test2(){

return “yixin”;

}

}

注意：我们现在的请求有两个“/test"和"/yixin/test"。

(2）编写配置

@Bean

public Docket docket() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())//配置Swagger信息

.select()

/**

• apis():指定扫描的接口

• RequestHandlerSelectors:配置要扫描接口的方式

• basePackage:指定要扫描的包

• any:扫面全部

• none:不扫描

• withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)

• withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)

*/

.apis(RequestHandlerSelectors.basePackage(“com.yixin.demo.controller”))

/**

• paths():过滤路径

• PathSelectors:配置过滤的路径

• any:过滤全部路径

• none:不过滤路径

• ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配

• regex:过滤指定路径:按照String的matches方法进行匹配

*/

.paths(PathSelectors.ant(“/yixin/**”))

.build();

}

分析：扫描路径com.yixin.demo.controller下的请求以/yixin开头的接口。

(3) 重启项目，访问 localhost:8080/swagger-ui.html

可以发现成功扫描到以/yixin请求开头的接口。

注意：.select().apis.paths.build是一套组合进行使用

六、配置Swagger开关

=============

6.1 enable

---

通过Docket对象的.enable方法来配置swagger是否启动

• true(默认）:开启

• false:关闭

@Bean

public Docket docket() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())//配置Swagger信息

.enable(false)//关闭swagger

.select()

.apis(RequestHandlerSelectors.basePackage(“com.yixin.demo.controller”))

.paths(PathSelectors.ant(“/yixin/**”))

.build();

}

更改为false后启动测试一下，发现无法进入到swagger页面

6.2 动态配置开关

---

需求：希望Swagger在开发环境中开启，在正式环境时不能使用

（1）判断是不是开发环境，可以设置一个flag表示用来表示：flag=1即表示生产环境

（2）将flag的值传给enable(flag)

实现：

(1) 在resources目录下新建两种springboot配置文件

开发环境：application-dev.properties

server.port=8090

正式环境：application-pro.properties

server.port=8070

目录如下：

(2)在主配置文件application.properties中激活开发环境

spring.profiles.active=dev

(3)到SwaggerConfig中的docket()方法中添加代码

a.首先给该方法传一个参数Environment的实例

Environment environment

b.设置要配置的Swagger环境：这里可以添加多个环境

Profiles profiles = Profiles.of(“dev”, “test”);

c.通过environment.acceptsProfiles方法判断是否处在上一步设定的dev/test环境中，返回一个boolean的值，我们用flag接收

boolean flag = environment.acceptsProfiles(profiles);

d.修改enable中的参数为flag，即通过flag来判断是否开启Swagger

.enable(flag)//通过flag判断是否开启

完整代码：

package com.yixin.demo.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.core.env.Environment;

import org.springframework.core.env.Profiles;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration //配置类

@EnableSwagger2// 开启Swagger2的自动配置

public class SwaggerConfig {

@Bean

public Docket docket(Environment environment) {

Profiles profiles = Profiles.of(“dev”, “test”);

boolean flag = environment.acceptsProfiles(profiles);

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())//配置Swagger信息

.enable(flag)

.select()

.apis(RequestHandlerSelectors.basePackage(“com.yixin.demo.controller”))

.paths(PathSelectors.ant(“/yixin/**”))

.build();

}

//配置文档信息

private ApiInfo apiInfo() {

Contact contact = new Contact(“联系人名字”, “http://xxx.xxx.com/联系人访问链接”, “联系人邮箱”);

return new ApiInfo(

“Swagger学习”, // 标题

“学习演示如何配置Swagger”, // 描述

“v1.0”, // 版本

“http://terms.service.url/组织链接”, // 组织链接

contact, // 联系人信息

“Apach 2.0 许可”, // 许可

“许可链接”, // 许可连接

new ArrayList<>()// 扩展

);

}

}

(4) 启动主程序测试：由于激活了dev开发环境，所以可以访问localhost:8090/swagger-ui.html

注意：由于我们激活的是dev环境，所有端口号是8090

成功开启swagger，如果我们修改主配置文件，激活pro正式发布环境

application.properties

spring.profiles.active=pro

再次重启主程序测试，访问端口8070对应的地址localhost:8070/swagger-ui.html

注意pro的端口号是：8070

无法进入，因为pro环境不在我们配置的test/dev环境中，所以无法开启

七、 配置API分组

==========

7.1 设置默认组名

---

如果没有配置分组，默认是default。

我们可以在docket通过**.groupName**中设置组名

@Bean

public Docket docket(Environment environment) {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.groupName(“yixin”)// 配置分组

.select()

.apis(RequestHandlerSelectors.basePackage(“com.yixin.demo.controller”))

.paths(PathSelectors.ant(“/yixin/**”))

.build();

}

启测试，可以看到组名更改为yixin

7.2  配置多个组

---

上述我们成功修改了组名，但是只有一个组，如果我们想要多个组呢？

观察代码可以知道，一个Docket实例就对应着一个组，因此我们配置多个docket就对应着多个组

我们新增两个Docket的bean实例

@Bean

public Docket docket1() {

return new Docket(DocumentationType.SWAGGER_2).groupName(“group1”);

}

@Bean

public Docket docket2() {

return new Docket(DocumentationType.SWAGGER_2).groupName(“group2”);

}

再次重启测试，就可以看到多个组并选择

八、实体配置

======

8.1 搭建实体

---

（1）新建实体类

在主程序同级目录下新建pojo包，其中新建Blog实体类

package com.yixin.demo.pojo;

import lombok.AllArgsConstructor;

import lombok.Data;

import lombok.NoArgsConstructor;

@AllArgsConstructor

@NoArgsConstructor

@Data

public class Blog {

private String name;

private Integer pwd;

}

注意：我们这里是导入了lombok依赖，自动添加get,set方法

org.projectlombok

lombok

注：如果没有添加get,set方法，在swagger页面实体类中是看不到属性值的。

（2） 编写对应请求接口

编写完实体类，我们在model中还是看不到的，我们还需在MyController中新增一个方法返回实体类的实例对象即可映射到实体项中

@RequestMapping(“/getBlog”)

public Blog getBlog() {

return new Blog();

}

（3）启动测试

成功显示实体类Blog

注意：这里之所以会出现Blog，是因为接口方法（Controller)的返回值上的实体都会显示在这里

8.2 常用注解

---

8.2.1实体类注解

我们可以在实体类上和其属性上添加注解来解释对应的属性

• @ApiModel为类添加注释

• @ApiModelProperty为类属性添加注释

（1）添加注解

@AllArgsConstructor

@NoArgsConstructor

@Data

@ApiModel(“博客实体”)

public class Blog {

@ApiModelProperty(“博客”)

private String name;

@ApiModelProperty(“密码”)

private Integer pwd;

}

（2）重启测试，即可以看到注释信息

8.2.2 接口注解

我们同样可以在Controller类和其中的方法上添加相应的注解

• @Api：为控制类添加注解

• @ApiOperation：为控制方法添加注解

（1)添加注解

@Api(tags = “Hello控制类”)

@RestController

public class MyController {

@ApiOperation(“Blog控制类”)

@RequestMapping(“/getBlog”)

public Blog getBlog() {

return new Blog();

}

（2）重启即可看到对应的注解

8.3 常用注解

---

| Swagger注解 | 简单说明 |

| — | — |

| @Api(tags = “xxx模块说明”) | 作用在模块类上 |

| @ApiOperation(“xxx接口说明”) | 作用在接口方法上 |

| @ApiModel(“xxxPOJO说明”) | 作用在模型类上：如VO、BO |

| @ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上，hidden设置为true可以隐藏该属性 |

| @ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上，类似@ApiModelProperty |

九、测试Swagger的使用

==============

9.1 测试传参

---

（1）我们在MyController中新增一个方法，参数为name，可以用**@ApiParam**给该参数添加注解

@GetMapping(“/name”)

public String getBlogName(@ApiParam(“博客名”) String name) {

return name;

}

（2）重启测试，可以看到我们添加的注释

（3）我们可以简单测试一下，点击Try it out；然后以json的格式输入用户名，然后点击Execute执行

可以看到报错了，这是因为我们是使用的是Get方式：是通过URL的方式传递的，而不是通过请求体单独传参

结论：不能通过GET/HEAD方式进行请求传参。

我们将代码修改一下，将GetMapping改为RequestMapping（不能用GET/HEAD）或PostMapping即可

@RequestMapping(“/name”)

public String getBlogName(@ApiParam(“博客名”) String name) {

return name;

}

进入页面：

注意：只能使用以下五种方式进行传参，不能使用GET/HEAD传参。

重新测试：

再次以json的格式输入参数name，可以看到成功了

（4） 如果担心选到GET/HEAD，那么就将Controller定义为@PostMapping

总结

我们总是喜欢瞻仰大厂的大神们，但实际上大神也不过凡人，与菜鸟程序员相比，也就多花了几分心思，如果你再不努力，差距也只会越来越大。实际上，作为程序员，丰富自己的知识储备，提升自己的知识深度和广度是很有必要的。

Mybatis源码解析

《一线大厂Java面试题解析+核心总结学习笔记+最新讲解视频+实战项目源码》，点击传送门，即可获取！

我们将代码修改一下，将GetMapping改为RequestMapping（不能用GET/HEAD）或PostMapping即可

@RequestMapping(“/name”)

public String getBlogName(@ApiParam(“博客名”) String name) {

return name;

}

进入页面：

注意：只能使用以下五种方式进行传参，不能使用GET/HEAD传参。

重新测试：

再次以json的格式输入参数name，可以看到成功了

（4） 如果担心选到GET/HEAD，那么就将Controller定义为@PostMapping

总结

我们总是喜欢瞻仰大厂的大神们，但实际上大神也不过凡人，与菜鸟程序员相比，也就多花了几分心思，如果你再不努力，差距也只会越来越大。实际上，作为程序员，丰富自己的知识储备，提升自己的知识深度和广度是很有必要的。

Mybatis源码解析

[外链图片转存中…(img-QpBOICRd-1714755629720)]

[外链图片转存中…(img-aNpk0aKD-1714755629721)]

《一线大厂Java面试题解析+核心总结学习笔记+最新讲解视频+实战项目源码》，点击传送门，即可获取！