Spring Boot-集成Swagger

最新推荐文章于 2024-06-03 08:30:00 发布

2401_84004044

最新推荐文章于 2024-06-03 08:30:00 发布

阅读量1.2k

点赞数 22

本文链接：https://blog.csdn.net/2401_84004044/article/details/137899589

版权

程序员专栏收录该内容

280 篇文章 1 订阅

订阅专栏

二、Swagger介绍

2.1一句话介绍 Swagger

2.2 Swagger特点

三、SpringBoot集成Swagger

四、配置Swagger API信息

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

5.1 默认状态

5.2 配置扫描接口

5.3 配置接口扫描过滤

六、配置Swagger开关

6.1 enable

6.2 动态配置开关

七、配置API分组

7.1 设置默认组名

7.2 配置多个组

八、实体配置

8.1 搭建实体

8.2 常用注解

8.2.1实体类注解

8.2.2 接口注解

8.3 常用注解

九、测试Swagger的使用

9.1 测试传参

这样的话就只有Post了。

9.2 传实体类参数

9.3 错误测试

十、拓展：其他皮肤

10.1 默认

10.2 bootstrap-ui

10.3 Layui-ui

10.4 mg-ui

结语

一、背景

====

无论是前端还是后端开发，都或多或少地被接口文档折磨过。

（1）前端经常抱怨后端给的接口文档与实际情况不一致。

（2）后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

二、Swagger介绍

===========

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。

我们只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。

2.1一句话介绍 Swagger

Swagger是一个接口文档生成工具，同时提供接口测试调用的辅助功能。

2.2 Swagger特点

号称世界上最流行的API框架

Restful Api 文档在线自动生成器 => API 文档与API 定义同步更新

直接运行，在线测试API

支持多种语言（如：Java，PHP等）

官网：https://swagger.io/

三、SpringBoot集成Swagger

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

注意：使用JDK1.8+

搭建步骤：

1.新建一个SpringBoot-web项目

2.添加Maven依赖

springfox-swagger2

io.springfox

springfox-swagger2

2.9.2

springfox-swagger-ui

io.springfox

springfox-swagger-ui

2.9.2

3.编写Controller测试是否能正常运行

@RestController

public class MyController {

@RequestMapping(“/test”)

public String test(){

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() {
自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。

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

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

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

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

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

总结

总的来说，面试是有套路的，一面基础，二面架构，三面个人。

最后，小编这里收集整理了一些资料，其中包括面试题（含答案）、书籍、视频等。希望也能帮助想进大厂的朋友

三面蚂蚁金服成功拿到offer后，他说他累了

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！

org.projectlombok

lombok

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

（2）编写对应请求接口

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

@RequestMapping(“/getBlog”)

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

因此收集整理了一份《2024年Java开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。[外链图片转存中…(img-A3cRxUcq-1713389081221)]

[外链图片转存中…(img-cc3Y9fyJ-1713389081222)]

[外链图片转存中…(img-bOAPkYWm-1713389081222)]

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

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

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

总结

总的来说，面试是有套路的，一面基础，二面架构，三面个人。

最后，小编这里收集整理了一些资料，其中包括面试题（含答案）、书籍、视频等。希望也能帮助想进大厂的朋友

[外链图片转存中…(img-GDfvXyel-1713389081223)]

[外链图片转存中…(img-pp5kuhWV-1713389081223)]

《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！

2401_84004044

关注

22
点赞
踩
28

收藏

觉得还不错? 一键收藏
0
评论
Spring Boot-集成Swagger

总的来说，面试是有套路的，一面基础，二面架构，三面个人。最后，小编这里收集整理了一些资料，其中包括面试题（含答案）、书籍、视频等。希望也能帮助想进大厂的朋友《互联网大厂面试真题解析、进阶开发核心学习笔记、全套讲解视频、实战项目源码讲义》点击传送门即可获取！lombok注：如果没有添加get,set方法，在swagger页面实体类中是看不到属性值的。（2）编写对应请求接口编写完实体类，我们在model中还是看不到的，我们还需在MyController中新增一个方法返回实体类的实例对象即可映射到实体项中。
复制链接

扫一扫