Swagger
前言
现在很多项目都开始使用前后端分离的架构方式了，前后端分离带来诸多好处的同时，也面临了一些问题，比如前后端开发人员的协同问题。
之前一般是通过文档的形式来定义接口，然后前后端开发人员根据接口去各自开发，但是测试的时候往往会发现有对应不上的情况！
前端添加一个字段，后端则可能修改一系列的方法，这种情况带来了很大的麻烦，因此Swagger应运而生！
目录
Swagger 概念
Swagger 使用场景
Swagger 配置-文档信息
Swagger 配置-接口扫描/过滤
Swagger 配置-分组
Swagger 配置-API注解
使用 Swagger测试接口
Swagger 概念
Swagger主要应用于前后端分离项目的协同开发，通过简单易用的配置，即可实现接口信息文档的实时更新，使得开发更见高效和便捷！
Swagger 使用场景
从开发的角度，这是对于前后端分离而且前后端人员分离的情况的！
如果是前后端分离，但是前后端人员不分离、甚至就是一个人承包了前后端，那实属没必要了~~~
从项目周期的角度，Swagger 在开发和测试时使用，上线则需要关闭。
Swagger 配置
1. 添加依赖包：swagger2、swagger-ui
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
添加配置类，并开启Swagger
package com.hwl.swgger01.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 //并开启Swagger public class SwaggerConfig { }
完成上门两步已经能使用Swagger了，非常简单。
测试访问 http://localhost:8080/swagger-ui.html
Swagger提供的界面有四个信息模块，如上图。
配置Swagger
实际开发中，我们一般不使用默认的配置，而是根据需要进行自定义自己的配置
Swagger的配置主要使用Docket这个实例提供的接口进行配置，从而实轻松现来接管默认配置。
注入配置实例，并修改Swagger信息
package com.hwl.swgger01.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
public class SwaggerConfig {
//配置并注入swagger的Docket实例,接管默认的配置信息
@Bean
public Docket docket(){
return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB
.apiInfo( setApiInfo() );
}
//配置swagger的apiInfo,参考默认配置修改
private ApiInfo setApiInfo(){
Contact contact = new Contact( "工程师01","hello.com","yunnanhwl@163.com" );//作者信息
return new ApiInfo(
"我的标题你做主",
"swagger有点好用",
"1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
运行查看修改结果：
自定义配置扫描接口
默认的配置是扫描出全部的接口的，例如springBoot默认的错误页面的接口。有时候我们只希望扫描自己想要的接口，这种情况也是通过Docket对象来设置：
//配置并注入swagger的Docket实例,接管默认的配置信息 @Bean public Docket docket(){ return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB .apiInfo( setApiInfo() ) .select() .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置扫描包 .build(); }
现在访问只有我们指定包下面的接口了：
通过源码发现这里的扫描策略有以下几种
- any //扫描全部
- none //都不扫描
- withMethodAnnotation //扫描方法上的注
- withClassAnnotation //扫描类上的注解，参数,例子:RestController.calss就只会扫描这样的类输出api
以上我们是通过Docket对象的apis来设置扫描哪些包，但有时候我们需要的包下面有些类或接口又是不需要扫描的，这时候需要使用过滤：
.apis() //配置扫描哪些包 .paths（）//配置哪些需要过滤
Swagger的内置开关
Swagger是开发提供了方便，但是一旦产品上线，测需要去掉Swagger，除了直接的代码摘除，其实Swagger提供了接口用来直接关闭：
.enable( flag ) //flag为false则关闭Swagger
一般会根据项目的环境来判断是否开启，当环境为开发、测试环境时开启：
分组协同开发
.groupName("Group01")
各组来实现自己的Docket配置，从而实现各组的实际对外显示情况：
//配置并注入swagger的Docket实例,接管默认的配置信息 @Bean public Docket docket(){ return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB .apiInfo( setApiInfo() ) .groupName("Group01") .select() .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置扫描哪些 .build(); } @Bean public Docket docket1(){ return new Docket( DocumentationType.SWAGGER_2 ) .apiInfo( setApiInfo() ) .groupName("Group02"); }
显示如下：
实体类
在前后端分离协同开发中，除了需要沟通接口外，实体类也是很重要的。
使用Swagger后，只要扫描显示的接口中，返回值带有某个实体类，那么该实体类会自动被Swagger加入到module中显示出来：
返回值：
@RequestMapping("/getUser")
public User hello(){
return new User( "lihua","123456" );
}
Swagger自动显示相关的实体：
此外，为了Swagger文档的友好性，Swagger还提供了一些注解来对类、方法、字段等进行一个额外的注释说明：
如：
@ApiModel("用户信息") 用来标注解释实体类，访问swagger时讲看到注释信息，提供了一定的友好度。
使用Swagger进行接口测试
swagger还直接提供了接口的测试功能，非常方便！
