一、学习目标

了解Swagger的概念及作用
掌握在项目中集成Swagger自动生成API文档

二、Swagger简介

前后端分离

前端 > 前端控制器、视图层
后端 > 后端控制器、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合

产生的问题

前后端集成，前端后者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

首先定义schema[计划的提纲]，并实时跟踪最新的API，降低集成风险

Swagger

世界上最流行的API框架
Resultful Api 文档在线自动生成器 => API文档与API定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）

三、SpringBoot集成Swagger

Springboot集成Swagger => Springfox，两个jar包

Springfox-swagger2
swagger-springmvc

使用Swagger

要求：jdk1.8以上，否则swagger2无法运行

四、案例

新建一个SpringBoot项目（选择web模块即可）
添加maven依赖

 <!-- swagger依赖 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

编写HelloController，测试确保运行成功!

/*** @author hyz* @create 2020-06-06 14:36*/
@RestController
public class HelloController {@GetMapping("/hello")public String hello(){return "hello";}
}

编写Swagger配置类（SwaagerConfig）

/*** @author hyz* @create 2020-06-06 14:41* swagger配置类*/
@Configuration
//开启swagger2
@EnableSwagger2
public class SwaggerConfig {}

访问测试:http://localhost:8080/swagger-ui.html,即可看到Swagger的界面

该界面主要分为四块区域，如下图所示：

五、配置Swagger

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger

  //配置Swagger的Docket的Bean实例@Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2);}

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

  @Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2);}//配置Swagger信息 = apiInfopublic ApiInfo apiInfo(){//作者信息Contact contact = new Contact("韩雨泽","http://www.hanyuze.top/","xxx@163.com");return new ApiInfo("韩雨泽的SwaggerAPI文档", //标题"帅气的小伙子", //描述"v1.0", //版本"http://www.hanyuze.top/", //组织链接contact, //联系人信息"Apache 2.0", //许可"http://www.apache.org/licenses/LICENSE-2.0", //许可链接new ArrayList()); //扩展}

Docket实例关联上apiInfo()

 @Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo();}//配置Swagger信息 = apiInfopublic ApiInfo apiInfo(){//作者信息//Contact contact = new Contact("联系人名字","联系人访问链接","联系人邮箱");Contact contact = new Contact("韩雨泽","http://www.hanyuze.top/","xxx@163.com");return new ApiInfo("韩雨泽的SwaggerAPI文档", //标题"帅气的小伙子", //描述"v1.0", //版本"http://www.hanyuze.top/", //组织链接contact, //联系人信息"Apache 2.0", //许可"http://www.apache.org/licenses/LICENSE-2.0", //许可链接new ArrayList()); //扩展}

重启项目，访问测试 http://localhost:8080/swagger-ui.html

六、配置扫描接口

构建Docket时通过select()方法配置怎么扫描接口

 @Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("韩雨泽")//通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口.select()//RequestHandlerSelectors 配置要扫描接口的方式//basePackage 根据包路径扫描接口//any():扫描全部，项目中所有接口都会被扫描到//none():不扫描接口//withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象//withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象.apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller")).build();}

重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类
还可以配置接口扫描过滤

 @Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口.select().groupName("韩雨泽")//RequestHandlerSelectors 配置要扫描接口的方式//basePackage 根据包路径扫描接口//any():扫描全部，项目中所有接口都会被扫描到//none():不扫描接口//withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象//withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象.apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller"))//过滤路径,例如这里只扫描请求以/admin开头的接口//any():任何接请求都扫描//none():任何请求都不扫描//regex():通过正则表达式控制//ant():通过ant()控制.paths(PathSelectors.ant("/admin/**")).build();}

七、配置Swagger开关

通过enable()方法配置是否启用Swagger,如果是false，Swagger将不能在浏览器访问了

 @Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("韩雨泽")//是否启用Swagger,如果为false,则不能在浏览器访问.enable(false)//通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口.select()//RequestHandlerSelectors 配置要扫描接口的方式//basePackage 根据包路径扫描接口//any():扫描全部，项目中所有接口都会被扫描到//none():不扫描接口//withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象//withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象.apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller"))//过滤路径,例如这里只扫描请求以/admin开头的接口//any():任何接请求都扫描//none():任何请求都不扫描//regex():通过正则表达式控制//ant():通过ant()控制.paths(PathSelectors.ant("/admin/**")).build();}

如何动态配置当项目处于开发环境(dev)环境时显示,生产环境(pro)不显示？

    //配置Swagger的Docket的Bean实例@Beanpublic Docket docker(Environment environment){//设置要显示的Swagger环境Profiles profiles = Profiles.of("dev","pro");//通过environment.acceptsProfiles判断是否处在自己设定的环境当中boolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("韩雨泽")//是否启用Swagger,如果为false,则不能在浏览器访问.enable(flag)//通过select()方法，配置扫描接口，RequestHandlerSelectors配置如何扫描接口.select()//RequestHandlerSelectors 配置要扫描接口的方式//basePackage 根据包路径扫描接口 //any():扫描全部，项目中所有接口都会被扫描到//none():不扫描接口//withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象//withMethodAnnotation: 扫描方法的注解，参数是一个注解的反射对象.apis(RequestHandlerSelectors.basePackage("cn.hyz.swagger.controller"))//过滤路径,例如这里只扫描请求以/admin开头的接口//any():任何接请求都扫描//none():任何请求都不扫描//regex():通过正则表达式控制//ant():通过ant()控制
//                .paths(PathSelectors.ant("/admin/**")).build();}

八、配置API分组

如果没有配置分组，默认是default。通过groupName()方法即可配置分组

    //配置Swagger的Docket的Bean实例@Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("韩雨泽") //配置分组//省略配置.......build();}

重启项目查看分组
如何配置多个分组？
配置多个分组只需要配置多个Docket即可

 //配置Swagger的Docket的Bean实例@Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("1") //配置分组//省略配置.......build();}//配置Swagger的Docket的Bean实例@Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("2") //配置分组//省略配置.......build();}//配置Swagger的Docket的Bean实例@Beanpublic Docket docker(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("3") //配置分组//省略配置.......build();}

4.重启项目查看即可

九、实体配置

新建一个实体类

/*** @author hyz* @create 2020-06-06 16:00*/
@ApiModel("用户实体类")
public class User {@ApiModelProperty("用户名")private String username;@ApiModelProperty("密码")private String password;
}

2.只要这个实体在请求接口的返回值上(即使是泛型)，都能映射到实体项中

@GetMapping("/user")
public User getUser(){return new User();
}

3.重启项目查看

注意：
并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@AapiModelProperty这两个注解是为实体添加注释的。

@ApiModel：为实体类添加注释
@AapiModelProperty：为实体类属性添加注释

更多注解请查看官网手册

十、扩展：网页皮肤

我们可以导入不同的包实现不同的皮肤定义:
1.默认的(访问http://localhost:8080/swagger-ui.html)

 <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

2.bootstrap-ui(访问http://localhost:8080/doc.html)

 <dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.1</version></dependency>

3.Layui-ui(访问http://localhost:8080/docs.html)

 <dependency><groupId>com.github.caspar-chen</groupId><artifactId>swagger-ui-lalyer</artifactId><version>1.1.3</version></dependency>

4.mg-ui(访问http://localhost:8080/document.html)

 <dependency><groupId>com.zyplayer</groupId><artifactId>swagger-mg-ui</artifactId><version>1.0.6</version></dependency>

Spirng Boot-Swagger相关推荐

java+swagger+侵入_Spring boot+Swagger配置无侵入式Restful接口(一)
最近一直遇到有人问我spring boot +swagger怎么配置无侵入式的restful接口,这段时间一直很忙,没有时间,刚好星期六,趁着休息时间给大家写个demo,在这里我就粘贴一些步骤,具体的 ...
Spring Boot + Swagger
http://springfox.github.io/springfox/docs/current/#customizing-the-swagger-endpoints 一.什么是Swagger? S ...
Spring Boot swagger之前后端分离
前后端分离详解现在的趋势发展,需要把前后端开发和部署做到真正的分离做前端的谁也不想用Maven或者Gradle作为构建工具做后端的谁也不想要用Grunt或者Gulp作为构建工具前后端需要通过接口来 ...
java+swagger+侵入_Spring boot+Swagger配置无侵入式Restful接口(二)
maven依赖自动配置额,看了前面第一种配置方式,是不是感觉有点麻烦呢?我也觉得,到时候去掉的时候,还需要进行删除配置啊,一大堆,还有可能到时候根本不知道. 所以,我决定自己写个让它自己就可以完成配 ...
spring boot 集成springfox，使用swagger对 API 接口进行测试管理的 demo 示例
1. 描述一个springboot项目集成 springfox 3.0,使用swagger对 API 接口进行测试管理的 demo示例. 环境: IDE(idea):2021.3 JDK:1.8 m ...
Spring Boot和Swagger UI
我已经一年没有从头开始开发Spring Web应用程序了,如果我不参加QA自动化工程师的培训,那么这段时间甚至会更长. 由于这个原因,我开发了一个示例REST应用程序. 除了Swagger,一切对我来 ...
mysqls压力测试怎么用_用 Swagger 测试接口，怎么在请求头中携带 Token？
松哥周末抽空给 Spring Security 系列也录制了一套视频,目录如下: 感兴趣的小伙伴戳这里-->Spring Boot+Vue+微人事视频教程今天的话题来自一个小伙伴在微信上的提问 ...
Spring Boot笔记
1.什么是SpringBoot 1.简介就是一个javaweb的开发框架以前Spring的配置太多,太麻烦,为了提高开发效率,于是开始提倡"约定大于配置",进而衍生出一些一站式 ...
Spring Boot
1.Spring Boot 1.回顾什么是Spring Spring是一个开源框架,2003 年兴起的一个轻量级的Java 开发框架,作者:Rod Johnson . Spring是为了解决企业级应用 ...
spring boot快速入门
1.什么是SpringBoot 一个javaweb的开发框架,和SpringMVC类似,对比其他javaweb框架的好处,官方说是简化开发,约定大于配置, you can "just run ...

Spirng Boot-Swagger

目录