Swagger2使用文档

一.swagger是什么?

1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

二.与springBoot整合

1.在pom.xml 文件中添加依赖

        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
            io.springfox
            springfox-swagger2
            2.9.2
        

2.注入配置

@Configuration
@EnableSwagger2
public class SaggerConfig {


	@Bean
	public Docket createRestApi () {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
													  //使用注解
													  .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
													  //包
													  //.apis(RequestHandlerSelectors.basePackage("com.qzt360"))
													  .paths(PathSelectors.any())
													  .build();
	}

	private ApiInfo apiInfo () {
		return new ApiInfoBuilder()
				//标题
				.title("awifi备案平台RESTful APIs")
				//描述
				.description("awifi备案平台RESTful APIs")
				//创建人
				.contact(new Contact("luowuhui","",XXXXX.com"))
				//版本
				.version("1.0").build();
	}
}

说明:

ApiInfo:api文档的基本信息

Docket:配置框架的工作方式

apiInfo():配置基本说明信息
apis(): 配置api选择方式(包,类注解,方法注解)
paths():配置扫描路径(所有,正则匹配)

3.定义api文档实例

@RestController
@Api(tags = "这个类的标签")
@ApiRes
@RequestMapping(value = "/test", method = RequestMethod.GET)
public class TestController {
	@ApiOperation(value = "描述接口作用", notes = "对接口的额外说明", response = String.class)
	@ApiImplicitParam(name = "te", value = "解析该参数作用..", required = true, dataType = "String", paramType = "path")
	@RequestMapping(value = "/test")
	public String test (String te) {
		return "tets";
	}

}

4.效果

访问路径:http://localhost:8080/swagger-ui.html

5.注解说明

@ApiOperation：用在请求的方法上，说明方法的用途、作用
value=“说明方法的用途、作用”
notes=“方法的备注说明”

@ApiImplicitParam ：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

swagger2 注解说明文档

三. idea使用Live Template快速生成@ApiOperation @ApiImplicitParam 配置

1. 创建 Live Templates group

@ApiOperation(value = "", notes = "", = Constant.SwP.Get)
@ApiImplicitParams(value = {$params$})`

2. params注入值

	groovyScript("def result=''; def params=\"${_1}\".replaceAll('[\\\\[|\\\\]|\\\\s]', '').split(',').toList(); for(i = 0; i < params.size(); i++) {result+=' @ApiImplicitParam(name=\"' + params[i] + ((i < params.size() - 1) ? '\",value=\"\"),\\n':'\",value=\"\")')}; return result", methodParameters()) 

3.使用

自动生成效果图