Swagger整合SpringBoot总结 使用方法
------------------------------Swagger(丝袜格儿)----------------------------
学习目标：
·了解Swagger的作用和概念
·了解前后端分离
·在SrpingBoot中集成Swagger
我们可以使用Swagger工具，帮助团队和企业能够更简单的进行用户以及API接口的开发
本文章末尾有源码
------------------------------Swagger简介------------------------------
前后端分离:
Vue+SpringBoot
后端时代:
前端只用管理静态页面;html==>后端。模板引擎 JSP=>后端是主力
前后端分离时代:
·后端:后端控制层(controller),服务层,数据访问层【后端团队】
·前端:前端控制层,视图层【前端团队】
·伪造后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来
·前后端如何交互？===>API
·前后端相对独立，松耦合;
·前后端甚至可以部署在不同的服务器上;
产生一个问题：
·前后端集成联调，前端人员和后端人员无法做到，及时协商，尽早解决，最终导致问题集中爆发;
解决方案:
·首先制定一个schema计划的提纲,实时更新最新API,降低集成的风险;
·早先年:制定word计划文档;
·前后端分离:
·前端测试后端接口:postman
·后端提供接口，需要实时更新最新的消息及改动！
--------------------------------Swagger--------------------------------
·号称世界上最流行的API框架
·RestFul Api风格 文档在线自动生成工具=>Api文档与Api定义同步更新
·直接运行，可以在线测试API接口;
·支持多种语言:(Java,Php…);
在项目中使用Swagger 需要springbox;
·swagger2
·swaggerUi
SpringBoot集成Swagger
1.新建一个SpringBoot = Web项目
2.导入相关依赖 Springfox Swagger2和Springfox SwaggerUi
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
3.编写一个Hello工程
package com.can.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
// /error
@RequestMapping(value = "/hello")
public String hello(){
return "hello";
}
}
4.配置Swagger==>Config
@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
}
5.测试运行：http://localhost:8080/swagger-ui.html
6.配置Swagger
Swagger的bean实例 Docket;
package com.can.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 {
//配置了Swagger 的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//配置Swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact DEFAULT_CONTACT = new Contact("谢炳灿", "https://me.csdn.net/qq_44619964", "[email protected]");
return new ApiInfo("Can的SwaggerAPI文档", //标题
"作者的描述", //文档描述
"1.0", //版本
"https://me.csdn.net/qq_44619964", //
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
7.Swagger配置扫描接口
Docket.select();
package com.can.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
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 {
//配置了Swagger 的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage指定要扫描的包
//.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.any():扫描全部
//.apis(RequestHandlerSelectors.any())
//.none()：都不扫描
//.apis(RequestHandlerSelectors.none())
//.withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
//.withMethodAnnotation():扫描方法上的注解
//withMethodAnnotation他只会去扫描类上有RestController注解的接口
//.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))
//一般用.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.paths():过滤什么路径
.paths(PathSelectors.ant("/can/**")) //ant("/can/**")过滤指定的路径
.build(); //build()
}
//配置Swagger信息=apiInfo
private ApiInfo apiInfo(){
//作者信息
Contact DEFAULT_CONTACT = new Contact("谢炳灿", "https://me.csdn.net/qq_44619964", "[email protected]");
return new ApiInfo("Can的SwaggerAPI文档", //标题
"作者的描述", //文档描述
"1.0", //版本
"https://me.csdn.net/qq_44619964", //
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
8.配置是否启动Swagger
.enable(false) //是否启动Swagger false:关闭Swagger
会提示 Could not render e, see the console.
//配置了Swagger 的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false) // enable是否启动Swagger false:关闭，则Swagger不能在浏览器中访问
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage指定要扫描的包
//.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.any():扫描全部
//.apis(RequestHandlerSelectors.any())
//.none()：都不扫描
//.apis(RequestHandlerSelectors.none())
//.withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
//.withMethodAnnotation():扫描方法上的注解
//withMethodAnnotation他只会去扫描类上有RestController注解的接口
//.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))
//一般用.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.paths():过滤什么路径
//.paths(PathSelectors.ant("/can/**")) //ant("/can/**")过滤指定的路径
.build(); //build()
//.select()到.build()是一套的 链式编程
}
如果只希望在生产环境中使用，在发布的时候不使用
·判断是不是在生产环境 flag=false
·注入enable(flag)
import org.springframework.core.env.Environment;
通过Environment去获取
Environment environment
//配置了Swagger 的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//Profiles.of:会retrun一个带有环境变量的实例
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev","test"); //可变长参数
//获取生产项目环境:
//environment.getActiveProfiles() 获得一个激活的文件
//environment.getDefaultProfiles() 获得默认的一个文件
//environment.acceptsProfiles(); //监听
//通过环境监听environment.acceptsProfiles 判断是否处在自己设定的环境当中
//如果配置文件没有指定激活的环境 则返回false
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//flag如果他是dev或者test环境(生产环境)则开启 Swagger
.enable(flag) // enable是否启动Swagger false:关闭，则Swagger不能在浏览器中访问
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage指定要扫描的包
//.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.any():扫描全部
//.apis(RequestHandlerSelectors.any())
//.none()：都不扫描
//.apis(RequestHandlerSelectors.none())
//.withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
//.withMethodAnnotation():扫描方法上的注解
//withMethodAnnotation他只会去扫描类上有RestController注解的接口
//.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))
//一般用.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.paths():过滤什么路径
//.paths(PathSelectors.ant("/can/**")) //ant("/can/**")过滤指定的路径
.build(); //build()
//.select()到.build()是一套的 链式编程
}
如果监听到了dev环境激活 则返回true 就启动Swagger否则关闭
9.如何给API分组(配置API文档的分组)
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName(“CAN_Swagger”)
如何配置多个分组;多个Docket实例即可 但是不要重复
@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
//配置了Swagger 的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//Profiles.of:会retrun一个带有环境变量的实例
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev","test"); //可变长参数
//获取生产项目环境:
//environment.getActiveProfiles() 获得一个激活的文件
//environment.getDefaultProfiles() 获得默认的一个文件
//environment.acceptsProfiles(); //监听
//通过环境监听environment.acceptsProfiles 判断是否处在自己设定的环境当中
//如果配置文件没有指定激活的环境 则返回false
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("CAN_Swagger")
//flag如果他是dev或者test环境(生产环境)则开启 Swagger
.enable(flag) // enable是否启动Swagger false:关闭，则Swagger不能在浏览器中访问
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage指定要扫描的包
//.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.any():扫描全部
//.apis(RequestHandlerSelectors.any())
//.none()：都不扫描
//.apis(RequestHandlerSelectors.none())
//.withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
//.withMethodAnnotation():扫描方法上的注解
//withMethodAnnotation他只会去扫描类上有RestController注解的接口
//.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))
//一般用.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
.apis(RequestHandlerSelectors.basePackage("com.can.controller"))
//.paths():过滤什么路径
//.paths(PathSelectors.ant("/can/**")) //ant("/can/**")过滤指定的路径
.build(); //build()
//.select()到.build()是一套的 链式编程
}
10.实体类配置
先创建一个实体类User
package com.can.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@ApiModel("用户实体类") //文档API给实体类的注释
public class User {
//@ApiModelProperty("用户名") //文档API给字段的注释
private String username;
//@ApiModelProperty("密码")
private String password;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
然后再Controller中新增一个方法
package com.can.controller;
import com.can.pojo.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
// /error
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
//如果只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
}
如果只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中 接口就是图片中的user()方法
测试结果
还有文档API给实体类的注释和文档API给字段的注释
将注释删掉
如下
package com.can.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体类") //文档API给实体类的注释
public class User {
@ApiModelProperty("用户名") //文档API给字段的注释
private String username;
@ApiModelProperty("密码")
private String password;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
测试结果
11.Controller类配置 文档注释
代码如下
package com.can.controller;
import com.can.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
//@Api在此处没用 只能用在model上 @Api("Hello控制类")
@RestController
public class HelloController {
// /error
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
//如果只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
//Operation接口,不是放在类上的，是方法上, @ApiParam("用户名")参数加上注释
@ApiOperation("Hello2方法类")
@GetMapping(value = "/hello2")
public String hello2(@ApiParam("用户名") String username){
return "hello"+username;
}
}
测试结果
12.Swagger测试接口
Curl:执行消息
执行了Get请求
请求了"http://localhost:8080/hello"
-H请求头："accept: /"自动生成的
-d参数:
Request URL:请求的地址
Code下是返回的结果错误会返回TypeError
这是成功的案例
测试一个失败的案例
新增一个方法
代码如下
package com.can.controller;
import com.can.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
//@Api在此处没用 只能用在model上 @Api("Hello控制类")
@RestController
public class HelloController {
// /error
@GetMapping(value = "/hello")
public String hello(){
return "hello";
}
//如果只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
@PostMapping(value = "/user")
public User user(){
return new User();
}
//Operation接口,不是放在类上的，是方法上, @ApiParam("用户名")参数加上注释
@ApiOperation("Hello2方法类")
@GetMapping(value = "/hello2")
public String hello2(@ApiParam("用户名") String username){
return "hello"+username;
}
//Operation接口,不是放在类上的，是方法上, @ApiParam("用户名")参数加上注释
@ApiOperation("Post测试类")
@PostMapping(value = "/postt")
public User postt(@ApiParam("用户名") User user){
int i =5/0;
return user;
}
}
接下来测似postt()方法 这个代码块 5/0会报错
启动测试
总结:
1.我们可以通过Swagger给一些比较难理解的属性和接口，增加注释信息
2.接口文档实时更新
3.可以在线测试
Swagger是一个优秀的工具，几乎所有大公司都有使用它。
【注意点】在正式发布的时候，关闭Swagger！！！出于安全考虑，而且还能节省运行的内存;
源码下载地址：https://gitee.com/can8888/SpringBoot-Swagger.git