SpringBoot【Swagger2的集成和使用】
Swagger2介绍
Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现。
SpringBoot集成Swagger2
首先添加依赖
<!--swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
编写Swagger2Config
配置类
@Configuration
public class SwaggerConfig {
//是否开启swagger,正式环境一般是需要关闭的,可根据springboot的多环境配置进行设置
@Value("${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
// 当前包路径
.apis(RequestHandlerSelectors.basePackage("com.jacky.controller"))
.paths(PathSelectors.any()).build();
}
//构建api文档的详细信息函数
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
//页面标题
.title("这是一个测试服务文档")
//创建人
.contact(new Contact("jacky","url","email"))
//版本号
.version("1.0")
在Controller层使用Swagger注解
/**
* class_name: UserController
* package: com.jacky.controller
* describe: 用户相关
* creat_user: Jacky
* creat_date: 2019/1/16
* creat_time: 上午9:14
**/
@Api("swaggerTestController相关api")
@RestController
@RequestMapping(value = "user")
public class UserController extends BaseController{
@PostMapping("update")
@ApiOperation(value="用户修改")
public Map<String,String> updateUser(@Valid @RequestBody UserReq userReq){
if(userReq.getId() == null || "".equals(userReq.getId())) {
throw new CommonException("0000", "更新时ID不能为空");
}
User user = new User();
user.setCode(userReq.getCode());
user.setName(userReq.getName());
user.setId(Long.parseLong(userReq.getId()));
userService.updateById(user);
Map<String,String> result = new HashMap<String,String>();
result.put("respCode", "01");
result.put("respMsg", "更新成功");
return result;
}
@GetMapping("/get/{id}")
@ApiOperation(value="用户查询(ID)")
@ApiImplicitParam(name="id",value="查询ID",required=true)
public Map<String,Object> getUser(@PathVariable("id") String id){
//查询
User user = userService.selectById(id);
if(user == null) {
throw new CommonException("0001", "用户ID:" + id + ",未找到");
}
UserResp resp = UserResp.builder()
.id(user.getId().toString())
.code(user.getCode())
.name(user.getName())
.status(user.getStatus())
.build();
Map<String,Object> result = new HashMap<String,Object>();
result.put("respCode", "01");
result.put("respMsg", "成功");
result.put("data", resp);
return result;
}
}
User实体类
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
//加入@ApiModel
@ApiModel
public class UserReq {
@ApiModelProperty(value="ID",dataType="String",name="ID",example="1020332806740959233")
String id;
@ApiModelProperty(value="编码",dataType="String",name="code",example="001")
@NotBlank(message = "编码不能为空")
String code;
@ApiModelProperty(value="名称",dataType="String",name="name",example="oKong")
@NotBlank(message = "名称不能为空")
String name;
}
启动Spirngboot项目,访问启动SpringBoot项目,访问 http://localhost:项目端口/swagger-ui.html
就可以看见文档了
Swagger2注解说明
-
@Api():作用于类上,表示这个类是swagger的资源。
-
tags = ”说明该类的作用“
-
-
@ApiOperation():用在请求的方法上,说明的方法的用户和作用
-
value=“说明方法的用途、作用”
-
notes="方法的备注说明“
-
-
@ApiImplicitParams():用在请求的方法上,表示一组参数说明,可以包含多个@ApiImplicitParam()
-
@ApiImplicitParam():指定一个请求参数的各个方面
-
name:参数名
-
value:参数的汉字说明
-
required:参数是否必须传
-
dataType:参数类型
-
defaultValue:参数的默认值
-
-
@ApiResponses():用在请求的方法上,表示一组响应。可以包含多个@ApiResponse()
-
@ApiResponse():用于表示一个错误的响应信息
-
code:数字
-
message:信息
-
response:抛出异常的类
-
-
@ApiModel():用在响应类上,表示一个返回响应数据的信息。
-
@ApiModelProperty():用在属性上,描述响应类的属性