场景

兄弟们，上一篇咱们演示了SpringBoot开发Restful Web项目是多么的简单啊，简直就是简单到爆炸。反正老哥我用了SpringBoot之后，是再写不想写原始的带有一堆配置的Spring项目了。

谁还不想简简单单把事情办了，好有更多时间陪女朋友逛街买裙子啊？啥？你没女朋友，那你还不想有更多时间玩优秀么兄弟，别这么死脑筋行不？

说正经的，还是找个女朋友是正道！

好的，有了Restful之后，开发后端API接口确实足够简单了，但是如何测试捏。

难道为了测试，就得把前端工程实现了？那还叫啥前后端分离呢。

难道要单独使用工具测试，比如Postman，功能导师挺全面，但是Postman完全不知道我们的项目是咋回事啊，URL参数都得自己一个一个填，多麻烦啊。

既然我们的程序都摆在这了，各个接口URL地址、参数都是确定的，就不能自动生成可视化的测试界面么，让我们把参数填填发起测试就行。

Swagger2用了就是爽

当然行咧，用Swagger2就是咧。不光自动生成可视化测试，还能自动生成接口文档。

别人来测试的时候，直接看到文档描述，都不用来问你了。将程序设计的懒人原则发挥到极致。

此处提一点，程序开发就是要足够懒，才能让需求方感到：咋这么容易、这么好用捏。

具体实现

好了，扯了一大堆，看看怎么实现。

1、导入依赖

我们还是使用上一章节中的Web项目进行演示，当然也可以使用任何的SpringBoot 2.x版本的项目进行添加Swagger2操作。

然后导入Swagger2相关的依赖，这样咱们的项目就能支持Swagger2咧，具体依赖项如下：

	<!-- 添加swagger2相关功能 -->
   	<dependency>
   		<groupId>io.springfox</groupId>
   		<artifactId>springfox-swagger2</artifactId>
   		<version>2.9.2</version>
   	</dependency>
   	<!-- 添加swagger-ui相关功能 -->
   	<dependency>
   		<groupId>io.springfox</groupId>
   		<artifactId>springfox-swagger-ui</artifactId>
   		<version>2.9.2</version>
   	</dependency>

TIPS：为啥用2.9.2版本？因为2.9.2是最新版本，炫酷呗！

2、添加Swagger2配置类

通过配置类配置Swagger2相关功能即可，相关要点咱都放注释中了。需要注意的是，不要感觉很难理解，这是人家定义好的类库，我们其实只要拿过来用就行了，Swagger2重点就是会使用就OK。

@Configuration // 告诉Spring容器，这个类是一个配置类，Spring容器得采用这个类的配置
@EnableSwagger2 // 启用Swagger2功能
public class Swagger2Config {
	/**
	 * 配置Swagger2相关的bean
	 */
	@Bean
    public 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默认会拦截静态资源，所以需要通过配置类配置下静态资源。

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
	@Override
	public 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注册为控制器，第二将其中方法返回值转换为json
public 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文档，或者开发完毕后的调整参数测试逻辑正确性。