SpringBoot-集成Swagger(1)

最新推荐文章于 2024-05-14 17:07:48 发布

2401_83817689

最新推荐文章于 2024-05-14 17:07:48 发布

阅读量285

点赞数 3

本文链接：https://blog.csdn.net/2401_83817689/article/details/137904410

版权

程序员专栏收录该内容

375 篇文章 0 订阅

订阅专栏

@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

@PostMapping(“/name”)

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

return name;

}

这样的话就只有Post了。

9.2 传实体类参数

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

@PostMapping(“/blog”)

public Blog getBlog(@ApiParam(“博客”) Blog blog) {

return blog;

}

（2）运行测试

（3）点击Execute测试

测试成功！

注意：一定要给Blog实体设置get和set方法，否则Response body相应体中博客名和密码都为会空。

9.3 错误测试

@PostMapping(“/blog”)

public Blog getBlogs(@ApiParam(“博客”) Blog blog) {

int i=10/0;

return blog;

}

此时测试肯定会报错，我们测试看看，可以看到500错误。

由此可见，swagger可以让我们很容易的进行前后端的交互测试

十、拓展：其他皮肤

=========

我们可以导入不同的包实现不同的皮肤定义：

10.1 默认

访问 http://localhost:8080/swagger-ui.htm

io.springfox

springfox-swagger-ui

2.9.2

自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

深知大多数Java工程师，想要提升技能，往往是自己摸索成长或者是报班学习，但对于培训机构动则几千的学费，着实压力不小。自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年Java开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，基本涵盖了95%以上Java开发知识点，真正体系化！

由于文件比较大，这里只是将部分目录截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新！

如果你觉得这些内容对你有帮助，可以扫码获取！！（备注Java获取）

学习分享，共勉

这里是小编拿到的学习资源，其中包括“中高级Java开发面试高频考点题笔记300道.pdf”和“Java核心知识体系笔记.pdf”文件分享，内容丰富，囊括了JVM、锁、并发、Java反射、Spring原理、微服务、Zookeeper、数据库、数据结构等大量知识点。同时还有Java进阶学习的知识笔记脑图（内含大量学习笔记）！