springBoot详解集成Swagger流程 springBoot详解集成Swagger流程

Swagger简介
SpringBoot集成Swagger
配置Swagger
Swagger配置扫描接口
配置是否启动Swagger
配置API文档的分组
实体类配置
常用的注解
小结

目标：

了解Swagger的作用和概念
了解前后端分离
在springBoot中集成Swagger

Swagger简介前后端分离
VUE+springBoot

后端：后端控制层、服务层、数据访问层
前端：前端控制层、视图层
前后端通过API进行交互
前后端相对独立，松耦合
可以部署在不同的服务器上

产生的问题
前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发
解决方案
首先定义计划的提纲，并实时跟踪最新的API，降低集成风险
Swagger

号称世界上最流行的API框架
Restful Api 文档在线自动生成器 =>API 文档与API 定义同步更新
直接运行，可以在线测试API接口；
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

SpringBoot集成Swagger 新建一个springboot-web项目
下载maven依赖https://mvnrepository.com/search?q=springfox

io.springfoxspringfox-swagger22.9.2io.springfoxspringfox-swagger-ui2.9.2

高版本是没有第5部的测试页面
3.0.0版本的要先在启动类中加上注解@EnableOpenApi先在导入io.springfoxspringfox-boot-starter
编写Controller，测试运行成功
配置Swagger=》在包Config下

package com.hxl.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration@EnableSwagger2 //开启swagger2public class SwaggerConfig {}

测试运行：http://localhost:8080/swagger-ui.html

文章图片

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

//配置了Swagger的Docket实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2); }

再通过ApiInfo()属性配置文档信息

private ApiInfo apiInfo(){//作者信息Contact contact = new Contact("王木木","https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343","11@qq.com"); return new ApiInfo("Swagger笔记", //标题"冲冲冲", //描述"v1.0。0", //版本"https://blog.csdn.net/qq_43585922?spm=1000.2115.3001.5343", //组织链接contact, //联系人信息"Apach 2.0 许可", //许可"许可链接", //许可连接new ArrayList<>()//扩展); }

Docket关联上ApiInfo

@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); }

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

文章图片

Swagger配置扫描接口构建Docket时通过select()方法配置怎么扫描接口。select()和build()是一套的

//配置了Swagger的Docket实例@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()/*RequestHandlerSelectors：要扫描接口的方式basePackage：指定要扫描的包any()：扫描全部none()：不扫描withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象withMethodAnnotation：扫描方法上的注解path()：过滤什么路径*/.apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))//.paths(PathSelectors.ant("/hxl/**")).build(); }

我们看之前的运行结构可以看到有base-error-controller和hello-controller，一旦使用了上述配置后，运行结果只有hello-controller

配置是否启动Swagger 通过enable()方法配置是否启用swagger

@Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//enable是否启动Swagger，默认为true，如果该位false则不能在浏览器中访问.enable(false).select()/*RequestHandlerSelectors：要扫描接口的方式basePackage：指定要扫描的包any()：扫描全部none()：不扫描withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象withMethodAnnotation：扫描方法上的注解path()：过滤什么路径*/.apis(RequestHandlerSelectors.basePackage("com.hxl.controller"))//.paths(PathSelectors.ant("/hxl/**")).build(); }

Swagger在生产环境中使用，在发布的时候不使用

判断是否是生产环境
注入enable()值

当我们有多个生产环境时。比如说application-dev.yaml和application-pro.yaml。动态设置当前项目处于dev时显示swagger，Pro是不显示

#哪个环境生效
spring.profiles.active=dev

设置我们的dev走8081，默认走8080，pro走8082
然后修改我们的配置

@Beanpublic Docket docket(Environment environment){//设置显示的Swagger环境Profiles profiles = Profiles.of("dev", "test"); //通过判断是否处在自己设定的环境中boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())//这里变成了flag.enable(flag).select().apis(RequestHandlerSelectors.basePackage("com.hxl.controller")).build(); }

此时我们就发现，如果我们走默认的8080是没有Swagger的，走8081才有

配置API文档的分组

@Beanpublic Docket docket(Environment environment){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("王木木"); //其余配置省略}

启动项目就发现我们的组别有了

文章图片

如果有多个分组怎么办？只需要配置多个docket即可

//其他的环境需要自己填@Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("天"); }@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("狼"); }

实体类配置创建一个实体类

package com.hxl.pojo; public class User {public String username; public String password; }

只要这个实体在请求接口的返回值上，就可以映射到实体项中

//只要我们的接口中，返回值存在实体类，他就会扫描到Swagger中@PostMapping("/user")public User user(){return new User(); }

测试

文章图片

此时发现我们的Model中有了User。如果有中文的注释，只需要在加两个注解

package com.hxl.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; //@Api("注释")@ApiModel("用户实体类")public class User {@ApiModelProperty("姓名")public String username; @ApiModelProperty("密码")public String password; }

测试

文章图片

常用的注解 Swagger的所有注解定义在io.swagger.annotations包下

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = https://www.it610.com/article/“xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上