SpringBoot之路(8)–使用Swagger2让咱滴测试和接口文档更轻松
场景
兄弟们，上一篇咱们演示了SpringBoot开发Restful Web项目是多么的简单啊，简直就是简单到爆炸。反正老哥我用了SpringBoot之后，是再写不想写原始的带有一堆配置的Spring项目了。
谁还不想简简单单把事情办了，好有更多时间陪女朋友逛街买裙子啊？啥？你没女朋友，那你还不想有更多时间玩优秀么兄弟，别这么死脑筋行不？
说正经的，还是找个女朋友是正道！
好的，有了Restful之后，开发后端API接口确实足够简单了，但是如何测试捏。
难道为了测试，就得把前端工程实现了？那还叫啥前后端分离呢。
难道要单独使用工具测试，比如Postman，功能导师挺全面，但是Postman完全不知道我们的项目是咋回事啊，URL参数都得自己一个一个填，多麻烦啊。
既然我们的程序都摆在这了，各个接口URL地址、参数都是确定的，就不能自动生成可视化的测试界面么，让我们把参数填填发起测试就行。
Swagger2用了就是爽
当然行咧，用Swagger2就是咧。不光自动生成可视化测试，还能自动生成接口文档。
别人来测试的时候，直接看到文档描述，都不用来问你了。将程序设计的懒人原则发挥到极致。
此处提一点，程序开发就是要足够懒，才能让需求方感到：咋这么容易、这么好用捏。
具体实现
好了，扯了一大堆，看看怎么实现。
1、导入依赖
我们还是使用上一章节中的Web项目进行演示，当然也可以使用任何的SpringBoot 2.x版本的项目进行添加Swagger2操作。
然后导入Swagger2相关的依赖，这样咱们的项目就能支持Swagger2咧，具体依赖项如下：
<dependency> <groupId>io.springfoxgroupId> <artifactId>springfox-swagger2artifactId> <version>2.9.2version> dependency> <dependency> <groupId>io.springfoxgroupId> <artifactId>springfox-swagger-uiartifactId> <version>2.9.2version> dependency>
TIPS：为啥用2.9.2版本？因为2.9.2是最新版本，炫酷呗！
2、添加Swagger2配置类
通过配置类配置Swagger2相关功能即可，相关要点咱都放注释中了。需要注意的是，不要感觉很难理解，这是人家定义好的类库，我们其实只要拿过来用就行了，Swagger2重点就是会使用就OK。
@Configuration // 告诉Spring容器，这个类是一个配置类，Spring容器得采用这个类的配置@EnableSwagger2 // 启用Swagger2功能public class Swagger2Config {/**
* 配置Swagger2相关的bean
*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com"))//com包下所有API都交给Swagger2管理.paths(PathSelectors.any()).build();}/**
* 此处主要是API文档页面显示信息
*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("演示项目API") //标题.description("学习Swagger2的演示项目") //描述.termsOfServiceUrl("http://www.forwhatsogood.com") //服务网址，此处是我个人网站地址.version("1.0") //版本.build();}}3、配置静态资源访问
由于Swagger2相关API文档html/css/js页面，而SpringBoot 2.x默认会拦截静态资源，所以需要通过配置类配置下静态资源。
@Configurationpublic class WebMvcConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 允许一下目录静态资源访问
registry.addResourceHandler("/statics/**").addResourceLocations("classpath:/statics/");
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}4、启动项目并进行查看、测试
启动项目，在之前的访问地址http://127.0.0.1:1007后面添加/swagger-ui.html，即访问http://127.0.0.1:1007/swagger-ui.html。
显示如下，可见我们控制器重的API方法都被列出来了。
点击其中一个API，然后点击try it out，则可以注入参数自动执行并显示结果，如下图，大家自己试试就OK。
5、通过注解自动生成API文档
通过在控制器上添加注解，可以在Swagger页面生成文档内容，修改控制器代码如下：
@Api(tags = "博客API") // 类文档显示内容@RestController // 通过该注解，第一将BlogController注册为控制器，第二将其中方法返回值转换为jsonpublic class BlogController {
@Autowired // 自动装配blogService
private BlogService blogService;
@ApiOperation(value = "根据id获取博客信息") // 接口文档显示内容
@GetMapping("/blog/{id}")
public BlogDo getOne(@PathVariable("id") long id) {
return blogService.getBlogById(id);
}
@ApiOperation(value = "获取博客列表") // 接口文档显示内容
@GetMapping("/blog")
public List<BlogDo> getList() {
return blogService.getBlogList();
}
@ApiOperation(value = "新增博客") // 接口文档显示内容
@PostMapping("/blog")
public void add(@RequestBody BlogDo blog) {
blogService.addBlog(blog);
}
@ApiOperation(value = "根据id修改博客信息") // 接口文档显示内容
@PutMapping("/blog/{id}")
public void update(@PathVariable("id") long id, @RequestBody BlogDo blog) {
// 修改指定id的博客信息
blog.setId(id);
blogService.updateBlog(blog);
}
@ApiOperation(value = "根据id删除博客") // 接口文档显示内容
@DeleteMapping("/blog/{id}")
public void delete(@PathVariable("id") long id) {
blogService.deleteBlog(id);
}}添加api注解后，Swagger页面显示如下，非常清晰简便的API文档，且可以直接点击调试，抓紧试试吧。
总结
Swagger2测试要比写前端代码调试，或者写Java Http代码调试，或者通过Postman等工具调试都要方便。
因为不用写代码、可视化、参数自动生成，我们只需要在指定参数位置填写参数即可。
当然也不是万能的，比如批量测试、并发测试，这个工具是玩不了的。
所以Swagger的使用场景是作为API文档，或者开发完毕后的调整参数测试逻辑正确性。
评论 (0)