spring boot 集成 Swagger2

一、简介

       Swagger2 是一款 RESTFUL 接口的文档在线自动生成和功能测试功能软件。它是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

       现在的项目基本都是采用前后端分离的技术实现的，维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。当然这是一种非常理想的状态，实际开发中却很少遇到这样的情况，接口总是在不断的变化之中，有变化就要去维护，而 Swagger 就是解决了维护接口文档这一工作。

二、集成步骤

2.1 添加 Maven 依赖

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

2.2 编写 Swagger2 配置类

// @EnableSwagger2 注解表示启用 Swagger2
@Configuration
@EnableSwagger2
public class SwaggerConfig {
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.zit")).paths(PathSelectors.any())
				.build();
	}
	// 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
			// 页面标题
			.title("Spring Boot 使用 Swagger2 构建RESTful API")
			// 版本号
			.version("v1")
			// 描述
			.description("API 描述").build();
	}
}

       这里提供一个配置类，配置一个 Docket Bean，这个 Bean 中，配置映射路径和要扫描的接口的位置。在 apiInfo 中，主要配置一下 Swagger2 文档网站的信息，例如网站的 title，网站的描述，联系人的信息，使用的协议等等。

       此时启动项目，输入http://localhost:端口号/swagger-ui.html，能够看到如下界面，说明已经配置成功了。

2.3 接口相关注解

        Swagger2 相关的接口的注解其实不是很多，而且很容易懂，下面先介绍部分注解。

# 用来标记当前Controller的功能
@Api

# 用来标记一个方法的使用 
@ApiOperation

# 用来查询相关信息
@GetMapping()

# 用来插入相关信息
@PostMapping()

# 用来修改相关信息
@PutMapping()

# 用来删除相关信息
@DeleteMapping()

2.4 构建 Controller 层代码

@Api(value = "用户相关操作api", tags = "用户相关接口")
@RestController
@RequestMapping("/labels")
public class UserInfoController {


	@ApiOperation(value = "查询用户信息", notes = "查询用户信息")
	@GetMapping(value = "/{id}")
	public UserInfo selectLabelInfos(@PathVariable Long id) {
		UserInfo userInfo = new UserInfo();
		System.out.println("接收到用户的id为："+id);
		userInfo.setId(id);
		userInfo.setUserName("张三");
		userInfo.setPassword("123456");
		return userInfo;
	}

	@ApiOperation(value = "插入用户信息", notes = "插入用户信息")
	@PostMapping()
	public UserInfo insertLabelInfo(@RequestBody UserInfo vm) {
		System.out.println(vm.toString());
		return vm;
	}

	@ApiOperation(value = "修改用户信息", notes = "修改用户信息")
	@PutMapping(value = "/{id}")
	public UserInfo updateLabelInfo(@PathVariable Long id, @RequestBody UserInfo vm) {
		System.out.println("接收到用户的请求id为："+id);
		System.out.println("接收到用户的请求对象为:"+vm.toString());
		return vm;
	}

	@ApiOperation(value = "删除用户信息", notes = "删除用户信息")
	@DeleteMapping("/{id}")
	public UserInfo deleteLabelInfo(@PathVariable Long id) {
		UserInfo userInfo = new UserInfo();
		userInfo.setId(id);
		System.out.println("接收到用户的请求id为："+id);
		return userInfo;
	}

	@ApiOperation(value = "根据对象参数查询用户信息", notes = "根据对象参数查询用户信息")
	@GetMapping(value = "/_search")
	public UserInfo searchParam(UserInfo userInfo) {
		System.out.println("接收到用户的参数为："+userInfo.toString());
		return userInfo;
	}
}

public class UserInfo {

	private Long id;
	
	private String userName;
	
	private String password;

	public Long getId() {
		return id;
	}

	public void setId(Long id) {
		this.id = id;
	}

	public String getUserName() {
		return userName;
	}

	public void setUserName(String userName) {
		this.userName = userName;
	}

	public String getPassword() {
		return password;
	}

	public void setPassword(String password) {
		this.password = password;
	}

	@Override
	public String toString() {
		return "UserInfo [id=" + id + ", userName=" + userName + ", password=" + password + "]";
	}
}

        启动程序，输入网址 http://localhost:端口号/swagger-ui.html，显示界面如图所示：

        接下来从上到下依次调用程序提供的方法，输出的结果如下所示：