Swagger2在spring boot API中的集成使用

背景

最近基于RESTful API开发Spring boot的接口,由于接口url众多，不同的url的uri对应的业务资源有不一样(业务逻辑是一样的，主要是通过改变接口的uri来辨别要处理对应的资源)，面对不同的接口，我们一般的想法就是，会创建一份RESTful API文档来记录所有接口的细节；如果想要做的有质量又有效率，然而不是一件简单的事情，会存在以下两个问题：
1.如果详细考虑接口请求，涉及到HTTP请求类型、HTTP请求头部信息、HTTP请求内容、HTTP安全验证的问题等等；想很好很快的完成这部分的文档就显得非常吃力了，对于调用这些接口的同事就会显得很吃力。
2.如果接口需要修改，则必须要同步修改接口文档，而文档与代码处于两个不同的媒介，这个同步起来很容易出问题，导致接口文档与实际接口功能出现不一致的现象。
swagger2就应运而生了，非常完美的与RESTful API进行结合；在程式代码里面集成使用swagger2可以在修改代码的时候，生成的接口文档也随之改变；大大的节约了时间；并且完美同步，质量高效。
swagger2是非常实用的插件，主要用于生成、描述、调用和可视化RESTful风格的WEB服务，在UI上面可以显示API的具体细节并且使客户端和文件系统作为服务器以同样的速度来更新显示；文件的方法、参数和模型紧密集成到服务端代码，允许API来始终保持同步。同时非常方便功能测试。以前是使用一些接口测试工具如postman，调试测试接口，手动找并输入url，找到各种需要的输入参数，少了什么条件参数，输错url或uri等等都会给测试带来很大的不便，如果各种条件参数和uri改变了，又得要重头再来try agin;简直要崩溃的节奏；还好swagger2帮你省了很多麻烦，只需要输入的参数的值就好了，其他一切有swagger2帮你同步更新上去，非常方便实用。

具体实现

1.Maven中的pom.xml依赖

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

2.创建Swagger2配置类
主要用使用swagger2的相关属性的配置

/*
	import必要的类
*/
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/*
	@configuration注解让Spring来加载该配置
	@EnableSwagger2注解启动swagger2
	@Bean注解加载bean类，返回的是Docket类实例
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
   
	/*
	swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
	1.apiInfo()方法用来创建该API的基本信息，这些信息会展现在文档页面上。信息包括：
	2.select()函数返回一个ApiSelectorBuilder实例来控制那些接口暴露给swagger2来展示。
	3.apis(RequestHandlerSelectors.basePackage("路径"))需要展示的接口通过扫描包的路径来获取路径下的
		controller定义api，并产生文档内容（除了那些被@ApiIgnore指定忽略的请求）多包可以使用逗号分隔。
	4.paths(PathSelectors.any())扫描路径下的所有API。
	5.build()创建生效。
	*/
	@Bean
	public Docket createRestApi() {
   
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.myself.thirdpartyinterface.controller"))
				.paths(PathSelectors.any())
				.build();
			
	}
	/*
	构建 api文档的展示基本信息函数；这些信息将会展示在接口文档Swagger-ui.html上面
	*/</