Spring Boot 整合Swagger2
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新 。接口的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
我们的RESTful API就有可能要面对多个开发人员或多个开发团队：IOS开发、Android开发、Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：
- 由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳；
- 随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象；
而swagger完美的解决了上面的几个问题，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能 来调试每个RESTful API。
使用流程如下：
1）引入相应的 maven 包：
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
2）编写Swagger2的 配置 类：
package com.trace.configuration;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
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;
/**
* Created by Trace on 2018-05-16.
* Desc: swagger2配置类
*/
@SuppressWarnings({"unused"})
@Configuration @EnableSwagger2
public class Swagger2Config {
@Value("${swagger2.enable}") private boolean enable;
@Bean("用户模块")
public Docket userApis() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("用户模块")
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.regex("/user.*"))
.build()
.apiInfo(apiInfo())
.enable(enable);
}
@Bean("客户模块")
public Docket customApis() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("客户模块")
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.regex("/custom.*"))
.build()
.apiInfo(apiInfo())
.enable(enable);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXXXX系统平台接口文档")
.description("提供子模块1/子模块2/子模块3的文档, 更多请关注公众号: 随行享阅")
.termsOfServiceUrl("https://xingtian.github.io/trace.github.io/")
.version("1.0")
.build();
}
}如上可见：
- 通过注解@EnableSwagger2开启swagger2，apiInfo是接口文档的基本说明信息，包括 标题 、描述、服务网址、联系人、版本等信息；
- 在Docket创建中，通过groupName进行分组，paths属性进行过滤，apis属性可以设置扫描包，或者通过注解的方式标识；通过enable属性，可以在appli cat ion-{profile}.properties文件中设置相应值，主要用于控制生产环境不生成接口文档。
3）controller层类和方法添加相关注解
package com.trace.controller;
import com.trace.bind.ResultModel;
import com.trace.entity.po.Area;
import com.trace.entity.po.User;
import com.trace.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.List;
/**
* Created by Trace on 2017-12-01.
* Desc: 用户管理controller
*/
@SuppressWarnings("unused")
@RestController @RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
@Resource private UserService userService;
@GetMapping("/query/{id}")
@ApiOperation("通过ID查询")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "path")
public ResultModel findById(@PathVariable int id) {
User user = userService.findById(id);
return ResultModel.success("id查询成功", user);
}
@GetMapping("/query/ids")
@ApiOperation("通过ID列表查询")
public ResultModel> findByIdIn(int[] ids) {
List users = userService.findByIdIn(ids);
return ResultModel.success("in查询成功", users);
}
@GetMapping("/query/user")
@ApiOperation("通过用户实体查询")
public ResultModel> findByUser(User user) {
List users = userService.findByUser(user);
return ResultModel.success("通过实体查询成功", users);
}
@GetMapping("/query/all")
@ApiOperation("查询所有用户")
public ResultModel> findAll() {
List users = userService.findAll();
return ResultModel.success("全体查找成功", users);
}
@GetMapping("/query/username")
@ApiOperation("通过用户名称模糊查询")
@ApiImplicitParam(name = "userName", value = "用户名称")
public ResultModel> findByUserName(String userName) {
List users = userService.findByUserName(userName);
return ResultModel.success(users);
}
@PostMapping("/insert")
@ApiOperation("新增默认用户")
public ResultModel insert() {
User user = new User();
user.setUserName("zhongshiwen");
user.setNickName("zsw");
user.setRealName("钟仕文");
user.setPassword("zsw123456");
user.setGender("男");
Area area = new Area();
area.setLevel((byte) 5);
user.setArea(area);
userService.save(user);
return ResultModel.success("新增用户成功", user.getId());
}
@PutMapping("/update")
@ApiOperation("更新用户信息")
public ResultModel update(User user) {
int row = userService.update(user);
return ResultModel.success(row);
}
@PutMapping("/update/status")
@ApiOperation("更新单个用户状态")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true),
@ApiImplicitParam(name = "status", value = "状态", required = true)
})
public ResultModel updateStatus(int id, byte status) {
User user = userService.updateStatus(id, status);
return ResultModel.success(user);
}
@DeleteMapping("/delete")
@ApiOperation("删除单个用户")
@ApiImplicitParam(value = "用户ID", required = true)
public ResultModel delete(int id) {
return ResultModel.success(userService.delete(id));
}
} 4）返回对象ResultModel
package com.trace.bind;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
/**
* Created by Trace on 2017-12-01.
* Desc: 接口返回结果对象
*/
@SuppressWarnings("unused")
@Getter @Setter @ApiModel(description = "返回结果")
public final class ResultModel {
@ApiModelProperty("是否成功: true or false")
private boolean result;
@ApiModelProperty("描述性原因")
private String message;
@ApiModelProperty("业务数据")
private T data;
private ResultModel(boolean result, String message, T data) {
this.result = result;
this.message = message;
this.data = data;
}
public static ResultModel success(T data) {
return new ResultModel<>(true, "SUCCESS", data);
}
public static ResultModel success(String message, T data) {
return new ResultModel<>(true, message, data);
}
public static ResultModel failure() {
return new ResultModel<>(false, "FAILURE", null);
}
public static ResultModel failure(String message) {
return new ResultModel<>(false, message, null);
}
} 5）ApiModel属性对象 — User实体
package com.trace.entity.po;
import com.trace.mapper.base.NotPersistent;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.List;
/**
* Created by Trace on 2017-12-01.
* Desc: 用户表tb_user
*/
@SuppressWarnings("unused")
@Data @NoArgsConstructor @AllArgsConstructor
@ApiModel
public class User {
@ApiModelProperty("用户ID") private Integer id;
@ApiModelProperty("账户名") private String userName;
@ApiModelProperty("用户昵称") private String nickName;
@ApiModelProperty("真实姓名") private String realName;
@ApiModelProperty("身份证号码") private String identityCard;
@ApiModelProperty("性别") private String gender;
@ApiModelProperty("出生日期") private LocalDate birth;
@ApiModelProperty("手机号码") private String phone;
@ApiModelProperty("邮箱") private String email;
@ApiModelProperty("密码") private String password;
@ApiModelProperty("用户头像地址") private String logo;
@ApiModelProperty("账户状态 0:正常; 1:冻结; 2:注销") private Byte status;
@ApiModelProperty("个性签名") private String summary;
@ApiModelProperty("用户所在区域码") private String areaCode;
@ApiModelProperty("注册时间") private LocalDateTime registerTime;
@ApiModelProperty("最近登录时间") private LocalDateTime lastLoginTime;
@NotPersistent @ApiModelProperty(hidden = true)
private transient Area area; //用户所在地区
@NotPersistent @ApiModelProperty(hidden = true)
private transient List roles; //用户角色列表
} 简单说下Swagger2几个重要注解：
@Api：用在请求的类上，表示对类的说明
- tags "说明该类的作用，可以在UI界面上看到的注解"
- value "该 参数 没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
- value="说明方法的用途、作用"
- notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
- value：参数的汉字说明、解释
- required：参数是否必须传
- paramType：参数放在哪个地方
- header –> 请求参数的获取：@RequestHeader
- query –> 请求参数的获取：@RequestParam
- path（用于restful接口）–> 请求参数的获取：@PathVariable
- body（不常用）
- form（不常用）
- dataType：参数类型，默认String，其它值dataType="Integer"
- defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：数字，例如400
- message：信息，例如"请求参数没填好"
- response：抛出异常的类
@ApiModel：主要有两种用途：
- 用于响应类上，表示一个返回响应数据的信息
- 入参实体：使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解进行描述的时候
@ApiModelProperty：用在属性上，描述响应类的属性
最终呈现结果：
如前所述：通过maven导入了swagger-ui：
io.springfox
springfox-swagger-ui
2.7.0
那么，启动应用后，会 自动生成 http ://{ root -path}/swagger-ui.html页面，访问后，效果如下所示：
可以在线测试接口，如通过ID查询的接口/user/query/{id}