springboot swagger
1. 介绍
目前大部分项目都是前后端分离，或者是以服务的形式暴露RESTful API接口，但是如何向调用方提供接口说明文档？如何快速单元测试我们的接口？如何在更改了接口之后快速的更新于接口文档中？带着这些问题，引入swagger。
特性：
- swagger可以生成互动性的API控制台
- 调用者和开发者尝试API
- 形成一种合作契约，让团队更加敏捷的开发
- 对代码有一定的入侵型
2. 集成
2.1 POM配置
pom中增加swagger的依赖
<!--Swagger Restful UI 集成依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
2.2 开启swagger
在入口程序的启动类（Application.java）上增加@EnableSwagger2的注解
@EnableSwagger2
@SpringBootApplication
public class Application {
public static void main(String[] args) {
//启动入口
SpringApplication.run(Application.class, args);
}
}
2.3 配置swagger
@Configuration
public class AppConfig {
/**
* 创建swagger ui的摘要
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 扫描的class的包路径
.apis(RequestHandlerSelectors.basePackage("pers.mateng.demo.springboot"))
// 只扫描类上有API注解的class
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
// 只扫描方法上有ApiOperation注解的方法
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
/**
* swagger ui的标题信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("标题")
.description("副标题")
.version("1.0")
.build();
}
}
2.4 声明 API
修改UserController，注意类注解（@Api）和方法注解（@ApiOperation）
@RestController
@RequestMapping(path="user")
@Api(tags="用户管理")
public class UserController {
@Autowired
private UserDao userDao;
@ApiOperation(value="查询用户", notes="测试无请求参数的swagger-ui")
@RequestMapping(method=RequestMethod.GET)
public List<User> findAll() {
return userDao.findAll();
}
@ApiOperation(value="增加用户-测试1", notes="测试application/x-www-form-urlencoded形式提交参数")
@RequestMapping(method=RequestMethod.POST)
public User add(@ModelAttribute User user) {
return userDao.save(user);
}
@ApiOperation(value="修改用户-测试1", notes="测试application/json形式提交参数")
@RequestMapping(path="/{id}", method=RequestMethod.PUT)
public User update1(@ApiParam(value="用户id") @PathVariable Long id, @RequestBody User user) {
User temp = userDao.findOne(id);
if(temp != null) {
temp.setName(user.getName());
temp.setAge(user.getAge());
return userDao.save(temp);
}
return null;
}
@ApiOperation(value="根据id查询用户", notes="测试path参数提交")
@GetMapping(path="/{id}")
public User findById(@ApiParam(value="用户id") @PathVariable Long id) {
return userDao.findOne(id);
}
@ApiOperation(value="根据id删除用户", notes="测试path参数提交")
@DeleteMapping(path="/{id}")
public Boolean del(@ApiParam(value="用户id") @PathVariable Long id) {
userDao.delete(id);
return Boolean.TRUE;
}
}
3. 验证
启动工程，使用eclipse的run as重新启动Application的main函数
使用浏览器访问http://localhost:8888/swagger-ui.html。即可查看UserControlerl中暴漏的接口
填写参数后，点击 “try it out” 即可发送请求
4. 进阶详解
4.1 @ModelAttribute 的参数说明
在swagger-ui上查看“增加用户-测试1”接口，发现该接口的描述并不完善，问题如下：
- 所有的请求参数都没有中文描述
- 增加用户时参数“id”是不需要的
那么接口调用方是无法更好的理解接口的使用，解决办法如下
方法一
- 使用 @ApiIgnore，让 swagger 忽略该实体类的参数
- 使用 @ApiImplicitParams 重新声明参数的类型、说明、是否必须、参数位置
详细代码如下：
@ApiOperation(value="增加用户-测试2")
@RequestMapping(path="add2", method=RequestMethod.POST)
@ApiImplicitParams({
@ApiImplicitParam(value="用户名", name="name", required=true, dataType="String", paramType="form"),
@ApiImplicitParam(value="年龄", name="age", required=false, dataType="integer", paramType="form")
})
public User add2(@ApiIgnore @ModelAttribute User user) {
return userDao.save(user);
}
方法二
- 升级 swagger的版本到2.7.0
- 使用 @ApiModelProperty(hidden=true) 隐藏参数
- 使用 @ApiModelProperty(value = "xxx") 描述参数的说明
- 使用 @ApiModelProperty(required=false) 标识参数是否必须输入
修改实体类User，==注意每个属性的注解==
@Entity
@Table(name="TB_USER")
public class User {
@Id
@GeneratedValue(strategy=GenerationType.AUTO)
@Column(name="U_ID")
@ApiModelProperty(hidden=true)
private Long id;
@Column(name="U_NAME", nullable = false, length=32, unique=true)
@ApiModelProperty(value = "用户名称", required=true)
private String name;
@Column(name="U_AGE", length=4)
@ApiModelProperty(value = "年龄", required=false)
private Integer age;
get/set...
}
4.2 @RequestBody 的参数说明
在 swagger-ui 上查看“修改用户-测试1”接口，发现该接口的描述并不完善，问题如下：
- 所有的请求参数都没有中文描述
- 为了追求 RESTful 风格，导致id声明了两次，在 Path 和 Resquestbody 中各声明了一次
所以接口调用方是无法更好的理解接口的使用，解决办法如下
方法一
不使用@Resquestbody 直接使用@ModelAttribute + @ApiImplicitParams的方法，==也就是4.1章节中的方法一==
代码如下：
@ApiOperation(value="修改用户-测试2", notes="测试application/x-www-form-urlencoded形式提交参数")
@RequestMapping(path="update2", method=RequestMethod.PUT)
@ApiImplicitParams({
@ApiImplicitParam(value="用户id", name="id", required=true, dataType="Integer", paramType="form"),
@ApiImplicitParam(value="用户名", name="name", required=true, dataType="String", paramType="form"),
@ApiImplicitParam(value="年龄", name="age", required=false, dataType="integer", paramType="form")
})
public User update2(@ApiIgnore @ModelAttribute User user) {
User temp = userDao.findOne(user.getId());
if(temp != null) {
temp.setName(user.getName());
temp.setAge(user.getAge());
return userDao.save(temp);
}
return null;
}
方法二
==也就是4.1章节中的方法二==
- 使用 @ApiModelProperty(hidden=true) 隐藏参数
- 使用 @ApiModelProperty(value = "xxx") 描述参数的说明
- 使用 @ApiModelProperty(required=false) 标识参数是否必须输入
在实体类 User上增加注解，代码如下：
@Entity
@Table(name="TB_USER")
public class User {
@Id
@GeneratedValue(strategy=GenerationType.AUTO)
@Column(name="U_ID")
@ApiModelProperty(hidden=true)
private Long id;
@Column(name="U_NAME", nullable = false, length=32, unique=true)
@ApiModelProperty(value = "用户名称", required=true)
private String name;
@Column(name="U_AGE", length=4)
@ApiModelProperty(value = "年龄", required=false)
private Integer age;
get/set……
}
4.3 @PathVariable/@RequestParam 的参数说明
在这两个注解的前面增加swagger的注解@ApiParam(value="xxx")
@DeleteMapping(path="/{id}")
public Boolean del(@ApiParam(value="用户id") @PathVariable Long id) {
userDao.delete(id);
return Boolean.TRUE;
}
@GetMapping(path="/name")
public String findByName(@ApiParam(value="用户名") @RequestParam String name) {
return name;
}
4.4 总结
在4.1章节和4.2章节中，处理参数的说明都使用了两种方法，概括的讲，方法一是在方法体的注解上想办法解决，方法二是在参数的属性上想办法解决。
方法一的优缺点分析：
- 缺点：写的代码多。
- 优点：适应性好，例如：有多个api接口都需要使用同一个javabean作为入参，但是每个接口实际暴露的参数不一样。就可以复用同一个javabean，而在各自的方法上处理。
- 优点：对javabean没有入侵性。
- 适合formdata/x-www-form-urlencoded表单提交。
方法二的优缺点：
- 缺点：复用性差，例如：有多个api接口都需要使用同一个javabean作为入参，但是每个接口实际暴露的参数不一样。不能复用同一个javabean。
- 缺点：如果一个javabean即作为入参，又作为出参。
- 优点：代码写的少。
- 适合application/json提交参数。
