环境集成
先引入相关依赖
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>20.0</version>
</dependency>
|
Swagger2配置类
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
|
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Value("${swagger.is.enable}")
private boolean swaggerIsEnable;
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.enable(swaggerIsEnable)
.apiInfo(apiInfo())
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com.bhy702.jfkj.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("JFKJ-CRM 接口文档")
.contact(new Contact("brbai","https://www.bhy702.com","baihongyuan702@163.com"))
.description("JFKJ-CRM swagger接口文档")
.version("1.0")
.build();
}
}
|
Swagger注解使用场景
常用注解解释：
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面，可以单独使用
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：只能用在@ApiResponses中，用于表达一个错误的响应信息
code：数字，状态码
message：提示信息
response：抛出的异常
生成实体model：
1
2
3
4
5
6
7
8
9
10
| @ApiModel(value = "用户model", description = "用户实体")
@Data
public class SysUserVo {
@ApiModelProperty(value = "实体id",example = "1",required = false)
private Integer id;
@ApiModelProperty(value = "实体名称")
private String name;
}
|
【例】生成效果：
常用接口注解使用
状态响应信息
1
2
3
4
5
6
7
8
| @ApiResponses(value = {
@ApiResponse(code = 0, message = "响应成功"),
@ApiResponse(code = 200, message = "响应成功"),
@ApiResponse(code = 401, message = "认证失败"),
@ApiResponse(code = 403, message = "权限不足"),
@ApiResponse(code = 404, message = "访问路径错误"),
@ApiResponse(code = 500, message = "服务器内部错误")
})
|
修饰类：
@Api(tags = "用户管理", description = "系统用户管理相关接口")
修饰方法：
@ApiOperation(value = "添加用户", notes="管理员添加用户", httpMethod = "POST")
修饰参数：
- 单个普通参数
1
2
3
4
5
6
| @ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String", paramType = "query")
或
@RequestMapping("/find")
public JsonResult add(@ApiParam(name = "username", value = "用户名", required = true) @RequestParam("username") String username){
}
|
- 单个对象参数
1
2
3
4
5
6
| @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User", paramType = "body")
或
@RequestMapping("/add")
public JsonResult add(@ApiParam(name = "user", value = "用户信息", required = true) @RequestBody User user){
}
|
- 单个数组参数
@ApiImplicitParam(name = "userIds", value = "用户id数组", required = true, dataType = "int",allowMultiple = true)
- 多个参数
1
2
3
4
5
| @ApiImplicitParams({
@ApiImplicitParam(name = "userIds", value = "用户id数组", required = true, dataType = "int",allowMultiple = true),
@ApiImplicitParam(name = "isAgree", value = "是否审批通过，1:通过，-1:拒绝", required = true, dataType = "int", paramType = "body"),
@ApiImplicitParam(name = "role", value = "用户角色", required = true, dataType = "String", paramType = "body")
})
|
【注意】@ApiImplicitParam与@ApiParam修饰对象参数的区别
@使用ApiImplicitParam文档中无对象结构：
@使用ApiParam修饰对象时含对象json结构：
