Spring Boot使用Swagger2自动化文档与测试

￡神魔★判官ぃ 2023-07-10 12:54 13阅读 0赞

***[点此查看全部文字教程、视频教程、源代码][Link 1]***

### 本文目录 ###

*  1. 场景
 *  2. Swagger2用了就是爽
 *  3. 具体实现
 *   *  3.1 导入依赖
     *  3.2 添加Swagger2配置类
     *  3.3 配置静态资源访问
     *  3.4 启动项目并进行查看、测试
     *  3.5 通过注解自动生成API文档
 *  4. 总结

# 1. 场景 #

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

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

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

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

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

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

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

# 2. Swagger2用了就是爽 #

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

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

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

# 3. 具体实现 #

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

## 3.1 导入依赖 ##

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

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

<dependency>
       		<groupId>io.springfox</groupId>
       		<artifactId>springfox-swagger2</artifactId>
       		<version>2.9.2</version>
       	</dependency>
       	
       	<dependency>
       		<groupId>io.springfox</groupId>
       		<artifactId>springfox-swagger-ui</artifactId>
       		<version>2.9.2</version>
       	</dependency>

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

## 3.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.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/");
    	}
    }

## 3.4 启动项目并进行查看、测试 ##

启动项目，在之前的访问地址`http://127.0.0.1:1007`后面添加`/swagger-ui.html`，即访问`http://127.0.0.1:1007/swagger-ui.html`。

显示如下，可见我们控制器重的API方法都被列出来了。

![图片描述][format_png]

点击其中一个API，然后点击try it out，则可以注入参数自动执行并显示结果，如下图，大家自己试试就OK。  
![图片描述][format_png 1]

## 3.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文档，且可以直接点击调试，抓紧试试吧。  
![图片描述][format_png 2]

# 4. 总结 #

Swagger2测试要比写前端代码调试，或者写Java Http代码调试，或者通过Postman等工具调试都要方便。

因为不用写代码、可视化、参数自动生成，我们只需要在指定参数位置填写参数即可。

当然也不是万能的，比如批量测试、并发测试，这个工具是玩不了的。

所以Swagger的使用场景是作为API文档，或者开发完毕后的调整参数测试逻辑正确性。

[Link 1]: https://studyingpanda.blog.csdn.net/article/details/105329926
[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcxLnN5Y2RuLmltb29jLmNvbS81ZTVhODRmZjAwMDFiZDM0MDg3MTA2OTgucG5n?x-oss-process=image/format,png
[format_png 1]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcxLnN5Y2RuLmltb29jLmNvbS81ZTVhODU3ZjAwMDE1MWU4MDg1MzA4ODMucG5n?x-oss-process=image/format,png
[format_png 2]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9pbWcxLnN5Y2RuLmltb29jLmNvbS81ZTVhODY2ZjAwMDE4YzM2MDg2MzA2ODMucG5n?x-oss-process=image/format,png