目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。
说的直白点，swagger就是帮你写接口说明文档的。
简单地使用swagger只需要三步。
1、引入swagger的依赖
目前推荐使用2.7.0版本,因为2.6.0版本有bug，而其他版本又没有经过验证
一：引入Swagger依赖库
<!--引入swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2、springBoot整合swagger
要使用swagger，我们必须对swagger进行配置，我们需要创建一个swagger的配置类，比如可以命名为SwaggerConfig.java
3、swagger的使用基于注解
接口有时候应该是分组的，而且大部分都是在一个controller中的，比如用户管理相关的接口应该都在UserController中，那么不同的业务的时候，应该定义/划分不同的接口组。接口组可以使用@Api来划分。
比如：
@Api(tags = "角色管理") // tags：你可以当作是这个组的名字。
@RestController
public class RoleController {
}
和
@Api(tags = "用户管理") // tags：你可以当作是这个组的名字。
@RestController
public class UserController {
}
我们可以使用@ApiOperation来描述controller下面的接口，比如：
@ApiOperation(value = "用户测试",notes = "用户测试notes")
@GetMapping("/test")
public String test(String id){
return "test";
}常用配置项：
- value：可以当作是接口的简称
- notes：接口的描述
- tags：可以额外定义接口组，比如这个接口外层已经有
@Api(tags = "用户管理")，将接口划分到了“用户管理”中，但你可以额外的使用tags，例如tags = "角色管理"让角色管理中也有这个接口文档。
上面使用了@ApiOperation来了描述接口，但其实还缺少接口请求参数的说明，下面我们分场景来讲。
场景一：请求参数是实体类。
（对于GET方式，swagger不推荐使用body方式来传递数据，所以虽然Spring MVC可以自动封装参数，但对于GET请求还是不要使用form-data，json等方式传递参数，除非你使用Postman来测试接口，swagger在线测试是不支持这个操作的）
此时我们需要使用@ApiModel来标注实体类，然后在接口中定义入参为实体类即可：
- @ApiModel：用来标类
- 常用配置项：
- value：实体类简称
- description：实体类说明
- 常用配置项：
- @ApiModelProperty：用来描述类的字段的意义。
- 常用配置项：
- value：字段说明
- example：设置请求示例（Example Value）的默认值，如果不配置，当字段为string的时候，此时请求示例中默认值为"".
- name：用新的字段名来替代旧的字段名。
- allowableValues：限制值得范围，例如
{1,2,3}代表只能取这三个值；[1,5]代表取1到5的值；(1,5)代表1到5的值，不包括1和5；还可以使用infinity或-infinity来无限值，比如[1, infinity]代表最小值为1，最大值无穷大。 - required：标记字段是否必填，默认是false,
- hidden：用来隐藏字段，默认是false，如果要隐藏需要使用true，因为字段默认都会显示，就算没有
@ApiModelProperty。
- 常用配置项：
如：
// 先使用@ApiModel来标注实体类
@ApiModel(value="用户登录表单对象",description="用户登录表单对象")
public class LoginForm { // 使用ApiModelProperty来标注字段属性。
@ApiModelProperty(value = "用户名",required = true,example = "root")
private String username;
@ApiModelProperty(value = "密码",required = true,example = "123456")
private String password;
// 此处省略入参赋值时需要的getter,setter,swagger也需要这个
}
如下将上面的实体类定义成入参：
@ApiOperation(value = "登录接口",notes = "登录接口的说明")
@PostMapping("/login")
public LoginForm login(@RequestBody LoginForm loginForm){
return loginForm;
}场景二：请求参数是非实体类。
对于非实体类参数，可以使用@ApiImplicitParams和@ApiImplicitParam来声明请求参数。@ApiImplicitParams用在方法头上，@ApiImplicitParam定义在@ApiImplicitParams里面，一个@ApiImplicitParam对应一个参数。@ApiImplicitParam常用配置项：
- name：用来定义参数的名字，也就是字段的名字,可以与接口的入参名对应。如果不对应，也会生成，所以可以用来定义额外参数！
- value：用来描述参数
- required：用来标注参数是否必填
- paramType有path,query,body,form,header等方式，但对于对于非实体类参数的时候，常用的只有path,query,header；body和form是不常用的。body不适用于多个零散参数的情况，只适用于json对象等情况。【如果你的接口是
form-data,x-www-form-urlencoded的时候可能不能使用swagger页面API调试，但可以在后面讲到基于BootstrapUI的swagger增强中调试，基于BootstrapUI的swagger支持指定form-data或x-www-form-urlencoded】
示例一：声明入参是URL参数
// 使用URL query参数
@ApiOperation(value = "登录接口2",notes = "登录接口的说明2")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",//参数名字
value = "用户名",//参数的描述
required = true,//是否必须传入
//paramType定义参数传递类型：有path,query,body,form,header
paramType = "query"
)
,
@ApiImplicitParam(name = "password",//参数名字
value = "密码",//参数的描述
required = true,//是否必须传入
paramType = "query"
)
})
@PostMapping(value = "/login2")
public LoginForm login2(String username,String password){
System.out.println(username+":"+password);
LoginForm loginForm = new LoginForm();
loginForm.setUsername(username);
loginForm.setPassword(password);
return loginForm;
}示例二：声明入参是URL路径参数（与上面的区别就是参数前多了@PathVariable注解）
// 使用路径参数
@PostMapping("/login3/{id1}/{id2}")
@ApiOperation(value = "登录接口3",notes = "登录接口的说明3")
@ApiImplicitParams({
@ApiImplicitParam(name = "id1",//参数名字
value = "用户名",//参数的描述
required = true,//是否必须传入
//paramType定义参数传递类型：有path,query,body,form,header
paramType = "path"
)
,
@ApiImplicitParam(name = "id2",//参数名字
value = "密码",//参数的描述
required = true,//是否必须传入
paramType = "path"
)
})
public String login3(@PathVariable Integer id1,@PathVariable Integer id2){
return id1+":"+id2;
} 示例三：声明入参是header参数
// 用header传递参数
@PostMapping("/login4")
@ApiOperation(value = "登录接口4",notes = "登录接口的说明4")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",//参数名字
value = "用户名",//参数的描述
required = true,//是否必须传入
//paramType定义参数传递类型：有path,query,body,form,header
paramType = "header"
)
,
@ApiImplicitParam(name = "password",//参数名字
value = "密码",//参数的描述
required = true,//是否必须传入
paramType = "header"
)
})
public String login4( @RequestHeader String username,
@RequestHeader String password){
return username+":"+password;
}
示例四：声明文件上传参数
// 有文件上传时要用@ApiParam，用法基本与@ApiImplicitParam一样，不过@ApiParam用在参数上
// 或者你也可以不注解，swagger会自动生成说明
@ApiOperation(value = "上传文件",notes = "上传文件")
@PostMapping(value = "/upload")
public String upload(@ApiParam(value = "图片文件", required = true)MultipartFile uploadFile){
String originalFilename = uploadFile.getOriginalFilename();
return originalFilename;
}
// 多个文件上传时，**swagger只能测试单文件上传**
@ApiOperation(value = "上传多个文件",notes = "上传多个文件")
@PostMapping(value = "/upload2",consumes = "multipart/*", headers = "content-type=multipart/form-data")
public String upload2(@ApiParam(value = "图片文件", required = true,allowMultiple = true)MultipartFile[] uploadFile){
StringBuffer sb = new StringBuffer();
for (int i = 0; i < uploadFile.length; i++) {
System.out.println(uploadFile[i].getOriginalFilename());
sb.append(uploadFile[i].getOriginalFilename());
sb.append(",");
}
return sb.toString();
}
// 既有文件，又有参数
@ApiOperation(value = "既有文件，又有参数",notes = "既有文件，又有参数")
@PostMapping(value = "/upload3")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",
value = "图片新名字",
required = true
)
})
public String upload3(@ApiParam(value = "图片文件", required = true)MultipartFile uploadFile,
String name){
String originalFilename = uploadFile.getOriginalFilename();
return originalFilename+":"+name;
}
响应是实体类：（返回对象如果是被@ApiModel标注的类对象那么就响应相对应的实体类）
前面在定义接口请求参数的时候有提到使用@ApiModel来标注类，如果接口返回了这个类，那么这个类上的说明也会作为响应的说明：
// 返回被@ApiModel标注的类对象 @ApiOperation(value = "实体类响应",notes = "返回数据为实体类的接口") @PostMapping("/role1") public LoginForm role1(@RequestBody LoginForm loginForm){ return loginForm; }
响应是非实体类：
swagger无法对非实体类的响应进行详细说明，只能标注响应码等信息。是通过@ApiResponses和@ApiResponse来实现的。@ApiResponses和@ApiResponse可以与@ApiModel一起使用。
// 其他类型的,此时不能增加字段注释，所以其实swagger推荐使用实体类
@ApiOperation(value = "非实体类",notes = "非实体类")
@ApiResponses({
@ApiResponse(code=200,message = "调用成功"),
@ApiResponse(code=401,message = "无权限" )
}
)
@PostMapping("/role2")
public String role2(){
return " {\n" +
" name:\"广东\",\n" +
" citys:{\n" +
" city:[\"广州\",\"深圳\",\"珠海\"]\n" +
" }\n" +
" }";
}