SpringBoot集成Swagger2，以及Swagger2常用API

为什么选择Swagger2

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

maven依赖

2.2.2





io.springfox
springfox-swagger2
${swagge
r.version}



io.springfox
springfox-swagger-ui
${swagger.version}

 

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