SpringBoot集成Swagger2，以及Swagger2常用API

为什么选择Swagger2

1. 接口文档在线自动生成
2. 接口在线调试功能
3. 文档与代码可以保持同步（因为文档的方法，参数和模型紧密集成到服务端的代码）

maven依赖

<properties>
<!-- swagger.version -->
<swagger.version>2.2.2</swagger.version>
</properties>


<!--swagger2【API文档】-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagge
r.version}</version>
</dependency>

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>

Swagger2配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* @version V1.0
* @Title: Swagger配置类
* @ClassName: com.newcapec.config.swagger.Swagger2Configuration.java
* @Description:
* @Copyright 2016-2017 - Powered By 研发中心
* @author: 王延飞
* @date:2017-12-11 8:20
*/

@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
.select()
//要扫描的API(Controller)基础包
.apis(RequestHandlerSelectors.basePackage("com.newcapec.controller"))
.paths(PathSelectors.any())
.build();
}

/**
* @Title: 构建API基本信息
* @methodName: buildApiInfo
* @param
* @return springfox.documentation.service.ApiInfo
* @Description
*
* @author: 王延飞
* @date: 2017-12-11 8:44
*/
private ApiInfo buildApiInfo() {

return new ApiInfoBuilder()
.title("业务系统<>API文档")
.description("这里除了查看接口功能外，还提供了调试测试功能")
.contact("王延飞")
.version("1.0")
.build();

}
}

Swagger2使用

@Api(value = "业务系统", description = "缴费用户注册、下单支付服务API")
@Controller
@RequestMapping(value = "/pay")
public class PayController {

private final Logger log = LoggerFactory.getLogger(this.getClass());

@Autowired
private PayService payService;

@ApiOperation(value = "下单支付统一接口", notes = "下单支付统一接口")
@RequestMapping(value = "", method = {RequestMethod.GET, RequestMethod.POST})
@ResponseBody
public String pay(HttpServletRequest request, RedirectAttributes redirectAttr) {


}

}

Swagger2的常用API

作用范围	注解	属性	值	备注
协议集描述 （修饰整个类，描述Controller的作用）	@Api	value	字符串	可用在class头上,class描述
		description	字符串
				@Api(value = "xxx", description = "xxx")
协议描述 （描述一个类的一个方法，或者说一个接口）	@ApiOperation	value	字符串	可用在方法头上.参数的描述容器
		notes	字符串
				@ApiOperation(value = "xxx", notes = "xxx")
单个参数描述	@ApiParam			用于方法，参数，字段说明
非对象参数集 （多个请求参数）	@ApiImplicitParams	{}	@ApiImplicitParam数组	可用在方法头上.参数的描述容器
				@ApiImplicitParams({@ApiImplicitParam1,@ApiImplicitParam2,...})
非对象参数描述 （一个请求参数）	@ApiImplicitParam	name	字符串 与参数命名对应	可用在@ApiImplicitParams里
		value	字符串	参数中文描述
		required	布尔值	true/false
		dataType	字符串	参数的数据类型 只作为标志说明，并没有实际验证 取值：Long、String
		paramType	字符串	查询参数类型（参数请求方式）:query/path
				query:对应@RequestParam?传递
				path: 对应@PathVariable{}path传递 body：以流的形式提交 仅支持POST header：参数在request headers 里边提交 form：以form表单的形式提交 仅支持POST
		defaultValue	字符串	在api测试中默认值
				用例参见项目中的设置
Response集 （HTTP响应整体描述）	@ApiResponses	{}	@ApiResponse数组	可用在方法头上.参数的描述容器
				@ApiResponses({@ApiResponse1,@ApiResponse2,...})
Response （HTTP响应其中1个描述）	@ApiResponse	code	响应码(int型)，可自定义	可用在@ApiResponses里
		message	状态码对应的响应信息	错误描述
				@ApiResponse(code = 200, message = "Successful")
实体	@ApiModel			描述一个Model的信息（这种一般用在post创建的时候，使用 )
实体属性	@ApiModelProperty			描述一个model的属性
使用该注解忽略这个API	@ApiIgnore

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性