SpringBoot集成Swagger
Swagger是动态接口文档,在前后端分离的项目中,接口文档越发显得重要,而swagger可以通过注解的方式,编写接口注释,顺便显示接口文档,还可以导出,方便很多。
Swagger介绍
没有API文档工具之前,基本都是手写API文档的,如有在Word
上写的,有在对应的项目目录下readme.md
上写的,每个公司都有每个公司的玩法,无所谓好坏。但是这种手写文档带来的弊端就是维护起来苦不堪言,对于接口容易发生变化的开发者来说,维护文档就是噩梦…. 好在现如今市场上书写API文档的工具有很多,常见的有 postman、yapi、阿里的RAP 但是能称之为框架的,估计也只有swagger
了。
优缺点
- 集成方便,功能强大
- 在线调试与文档生成
- 代码耦合,需要注解支持,但不影响程序性能
快速使用
- 添加依赖
<dependency>
<groupId>com.battcn</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.4.5-RELEASE</version>
</dependency>
- 配置属性
配置spring.swagger.enabled
开启swagger
的使用
spring:
swagger:
base-package: com.springboot # 扫描包路径
enabled: true
- 实体类
@ApiModel
public class User implements Serializable {
private static final long serialVersionUID = 8655851615465363473L;
private Long id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
// TODO 省略get set
}
- Controller
@RestController
@RequestMapping("/users")
@Api(tags = "1.1", description = "用户管理", value = "用户管理")
public class UserController {
private static final Logger log = LoggerFactory.getLogger(UserController.class);
@GetMapping
@ApiOperation(value = "条件查询(DONE)")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
@ApiImplicitParam(name = "password", value = "密码", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
})
public User query(String username, String password) {
log.info("多个参数用 @ApiImplicitParams");
return new User(1L, username, password);
}
@GetMapping("/{id}")
@ApiOperation(value = "主键查询(DONE)")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH),
})
public User get(@PathVariable Long id) {
log.info("单个参数用 @ApiImplicitParam");
return new User(id, "u1", "p1");
}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除用户(DONE)")
@ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH)
public void delete(@PathVariable Long id) {
log.info("单个参数用 ApiImplicitParam");
}
@PostMapping
@ApiOperation(value = "添加用户(DONE)")
public User post(@RequestBody User user) {
log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
return user;
}
@PutMapping("/{id}")
@ApiOperation(value = "修改用户(DONE)")
public void put(@PathVariable Long id, @RequestBody User user) {
log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 ");
}
}
- 主函数上配置
@EnableSwagger2Doc
@EnableSwagger2Doc
@SpringBootApplication
public class Chapter10Application {
public static void main(String[] args) {
SpringApplication.run(Chapter10Application.class, args);
}
}
效果
打开 http://localhost:8080/swagger-ui.html