SpringBoot集成Swagger快速上手

什么是Swagger

再谈Swagger之前我们先来了解下经常谈到的前后端分离技术

前后端分离：

• 前端–>前端的控制层，视图层。（专业的前端团队开发）
• 后端–>后端控制层、服务层、数据访问层（专业的后端团队开发）
• 前后端的交互是通过API来进行的，关于API的 约定该怎么处理呢？

早期：后端编写文档（协同文档），前端根据文档解析接口然后渲染视图！
问题：前后端集成，前端或者后端无法做到：及时协商！最终可能导致问题集中爆发或者项目延时！
所以Swagger就出现了。

什么是Swagger?

• 号称世界上最流行的API框架
• Restful api自动生成文档，和代码对应的
• 直接运行测试接口，不用下载postman
• 支持多种语言：（Java，PHP等）
• 官网：https://swagger.io/

集成Swagger

基础集成

1. 导入依赖

<dependency>
	<groupId>io.springfoxgroupId>
	<artifactId>springfox-swagger2artifactId>
	<version>2.9.2version>
dependency>

<dependency>
	<groupId>io.springfoxgroupId>
	<artifactId>springfox-swagger-uiartifactId>
	<version>2.9.2version>
dependency>

2. 编写配置

@Configuration
public class SwaggerConfig {
	// 注册bean Docket
	@Bean
	public Docket docket(){
		return new Docket(DocumentationType.SWAGGER_2);
	}
} 
// 主启动类开启配置！
@SpringBootApplication
// 使Swagger生效，默认是不开启！@EnableSwagger2
@EnableSwagger2
public class SpringbootPlusApplication {
	public static void main(String[] args) {
		SpringApplication.run(SpringbootPlusApplication.class, args);
	}
}

3. 启动测试：
   swagger-ui的默认访问地址是当前项目下的swagger-ui.html页面
   
   我们访问地址测试下：http://localhost:8080/swagger-ui.html
   

4. 编写Controller

@RestController
public class HelloController{

	@RequestMapping("/hello")
	public String hello(){
		return "hello"
	}
}

6. 访问
   
   注意：写Controller的之后一定要精确到方法！

所以要么使用@GetMapping这中形式，要么使用@RequestMapping(value="/hello",method=RequestMethod.GET)

配置Swagger
主要是配置两个核心对象Docket和ApiInfo。
1.构建Docket对象
Docket对象指代的就是我们这个文档Document，他的一些主要配置如下：

参数名称	参数描述
apiInfo	文档的一些描述信息，包括文档的标题，作者，遵循的开源协议等等
group	组名称，当我们的api接口太多的时候，我们就可以按照功能划分成不同的组
enabled	是否开启，默认是不开启的
genericsNamingStrategy	默认类型名称策略
applyDefaultResponseMessages	是否返回默认的结果信息
host	api文档地址
pathMapping	路径映射
apiSelector	api选择器，可以选择让哪些api显示
enableUrlTemplating	开启urlTemplate模板
vendorExtensions	扩展属性
documentationType	文档类型

@Bean
 public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2) //文档类型
                        .apiInfo(apiInfo()); // 配置文档信息！
 } 

2. 配置文档信息 apiInfo
   主要参数配置如下：

参数名称	参数描述
title	文档的标题
description	文档的描述信息
version	文档的版本号
termsOfServiceUrl	设置文档的License信息地址
contact	联系人
license	遵循的协议
licenseUrl	协议地址

private ApiInfo apiInfo(){
       Contact contact = new Contact("coding","https://www.xza.com","[email protected]");//联系方式
       return new ApiInfo(
               "SpringBoot-Plus 接口文档信息",
               "所有的测试请求地址",
               "v1.0", //版本号
               "https://www.xza.com/", //组织连接
               contact,
               "Apache 2.0", //采用的协议
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList<>());
}
   

3. 配置接口扫描，需要哪些被扫描到文档中

@Bean
public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
               		   .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.coding.controller"))
                        .build();
}
  

常用方法说明：

any() #扫描所有，项目的所有接口都会被扫描的
none() #不扫描接口
basePackage() #根据包路径扫描
withMethodAnnotation(GetMapping.class) #通过方法注解扫描！ 比如GetMapper.class
withClassAnnotation(Controller.class) #通过类上的注解扫描

3. 设置哪些接口不被扫描
   

@Bean
public Docket docket(){
        return
                new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo()) // 配置文档信息！
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.coding.controller"))
						// 配置path过滤请求！只扫描以 /shiqi 开头的请求！
                        .paths(PathSelectors.ant("/shiqi/**"))
                        .build();
}

配置Swagger的开关

test、dev环境下才可以显示swagger-ui,prod不显示

@Bean
public Docket docket(){
       return
              new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(false) // 如果是false就无法在浏览器中访问！
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.coding.controller")) //扫描哪个包下的接口
                    .paths(PathSelectors.ant("/kuang/**")) //配置请求路径
                    .build();
}

这里的false应该是一个变量：技巧点！通过Profiles类来获取限定咱们的开发环境!

@Bean
public Docket docket(Environment environment){
       // 设置要显示的swagger环境
       Profiles of = Profiles.of("dev", "test");
       // 判断是否处于该环境！
       boolean b = environment.acceptsProfiles(of);
       return
             new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo()) // 配置文档信息！
                   .enable(b) // 如果是false就无法在浏览器中访问！
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.coding.controller"))
                   .paths(PathSelectors.ant("/kuang/**"))
                   .build();
}

配置API分组

@Bean
public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
} 
    
@Bean
public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
  
@Bean
public Docket docket3(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

实体配置

1. 新建一个实体类

// 和注释差不多，但是会被Swagger识别
@ApiModel("用户实体")
public class User {
     @ApiModelProperty("用户名")
     private String username;
     @ApiModelProperty("密码")
     private String password;
}

2. 请求的接口配置！如果能够看到实体类配置！如果这个实体类在请求的返回值或者泛型中，那么就会被映射！

// 只有返回值用到才会显示
@GetMapping("/getUser")
public User getUser(){
	return new User();
}

接口上的配置

@Api(tags="AAAAA测试")
@RestController
public class HelloController {
	@ApiOperation("coding的接口")
	@PostMapping("/coding")
	public String coding(@ApiParam("这个名字会被返回！") String username){
		return username;
	} 
	@GetMapping("/kuang/hello")
	public String hello(){
		return "hello,Swagger";
	} 
	// 只有返回值用到才会显示
	@GetMapping("/getUser")
	public User getUser(){
		return new User();
	}
}

扩展：皮肤包

1、默认的 http://localhost:8081/swagger-ui.html

<dependency>
      <groupId>io.springfoxgroupId>
      <artifactId>springfox-swagger-uiartifactId>
      <version>2.9.2version>
dependency>

2、BootStrap-ui http://localhost:8080/doc.html

<dependency>
      <groupId>com.github.xiaoymingroupId>
      <artifactId>swagger-bootstrap-uiartifactId>
      <version>1.9.6version>
dependency>

3、Layui的框架 http://localhost:8080/docs.html

<dependency>
     <groupId>com.github.caspar-chengroupId>
     <artifactId>swagger-ui-layerartifactId>
     <version>1.1.3version>
dependency>

4、mg-ui http://localhost:8080/document.html

<dependency>
    <groupId>com.zyplayergroupId>
    <artifactId>swagger-mg-uiartifactId>
    <version>1.0.6version>
dependency>