13.玩转Spring Boot 集成swagger2

玩转Spring Boot 集成swagger

      在使用Spring Boot 开发Restful API，你是否在为写接口文档而郁闷呢？那么swagger一定适合你。使用swagger你可以有份很强大的Restful API文档。使用Spring Boot与Swagger集成我只能用非常简单来形容，接下来就具体说说。

1.pom.xml加入依赖

      创建工程后，打开pom.xml加入以下依赖：

			io.springfox
			springfox-swagger2
			2.6.1
		
		
			io.springfox
			springfox-swagger-ui
			2.6.1
		

2.创建入口启动类

      创建入口启动类，代码如下：

package com.chengli.springboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import com.google.common.base.Predicate;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static com.google.common.base.Predicates.*;

@SpringBootApplication
@EnableSwagger2 //启用swagger
public class MainConfig {
	public static void main(String[] args) {
		SpringApplication.run(MainConfig.class, args);
	}

	/**
	 * 这里是可以分组定义多个Docket，我这里举例定义了两个，一个是业务文档类型，一个是财务文档类型。
	 * 定义了多个分组后，在页面上提供了一个下拉来选择组，具体运行起来看看就知道了。
	 * 我这个是参照官方的代码改了改，有的删了，具体的大家看官方文档吧，
	 * 地址：http://springfox.github.io/springfox/docs/current/#plugins-available-for-extensibility
	 * 
	 */
	
	/**业务文档*/
	@Bean
	public Docket businessDocket() {
		return new Docket(DocumentationType.SWAGGER_2)
				.groupName("业务文档") //分组名称
				.select()
				.paths(businessPaths()) //指定路径处理PathSelectors.any()代表所有的
				.build()
				.apiInfo(apiInfo());
	}
	@SuppressWarnings("unchecked")
	private Predicate businessPaths() {
		return or(PathSelectors.regex("/user.*"));//这里是正则表达式
	}
	
	
	/**财务文档*/
	@Bean
	public Docket financeDocket() {
		return new Docket(DocumentationType.SWAGGER_2)
				.groupName("财务文档")//分组名称
				.select()
				.paths(financePaths())//指定路径处理PathSelectors.any()代表所有的
				.build()
				.apiInfo(apiInfo());
	}
	@SuppressWarnings("unchecked")
	private Predicate financePaths() {
		return or(PathSelectors.regex("/finance.*"));//这里是正则表达式
	}


	/**指定了页面显示的信息，标题、描述*/
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("使用Spring Boot 集成 swagger")
				.description("玩转Spring Boot 博客地址：http://blog.csdn.net/cl_andywin").build();
	}
	
}

3.创建Controller

      （1）创建用户实体

package com.chengli.springboot.swagger.pojo;

public class User {
	private Long id;
	private String name;
	private String sex;
	private Integer age;

	public Long getId() {
		return id;
	}

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

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public String getSex() {
		return sex;
	}

	public void setSex(String sex) {
		this.sex = sex;
	}

	public Integer getAge() {
		return age;
	}

	public void setAge(Integer age) {
		this.age = age;
	}

	@Override
	public String toString() {
		return "User [id=" + id + ", name=" + name + ", sex=" + sex + ", age=" + age + "]";
	}

}

   

   （2）创建controller代码如下

package com.chengli.springboot.swagger.controller;

import java.util.List;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.chengli.springboot.swagger.pojo.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/user")
@Api(tags = "user")
public class UserController {
	public List getUserList() {
		return null;
	}

	/*
	 * 这里就写两个例子啊，其余的都一样了，就不在写了。
	 * 
	 */

	/**
	 * 增加的时候，我通过用参数的方式来增加
	 * 
	 * @param user
	 * @return
	 */
	@ApiOperation("增加用户信息")
	@ApiImplicitParams({
			@ApiImplicitParam(paramType = "query", name = "name", dataType = "String", required = true, value = "姓名", defaultValue = "成立"),
			@ApiImplicitParam(paramType = "query", name = "sex", dataType = "String", required = true, value = "性别", defaultValue = "男"),
			@ApiImplicitParam(paramType = "query", name = "age", dataType = "int", required = false, value = "年龄", defaultValue = "18") })
	@RequestMapping(method = RequestMethod.POST)
	public User save(User user) {
		// 这里为了方便直接将输入内容返回
		return user;
	}

	/**
	 * 修改的时候，我通过使用JSON的方式来修改
	 * 
	 * @param id
	 * @param user
	 * @return
	 */
	@ApiOperation(value = "修改用户信息", notes = "根据ID修改用户信息")
	@ApiImplicitParams({
			@ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", required = true, dataType = "Long"),
			@ApiImplicitParam(paramType = "body", name = "user", value = "用户实体", required = true, dataType = "User") })
	@RequestMapping(value = "/{id}", method = RequestMethod.PUT)
	public User update(@PathVariable Long id, @RequestBody User user) {
		// 这里为了方便直接将输入内容返回
		return user;
	}
}

到这里就已经配置好了，启动试试吧，在浏览器上输入：http://localhost:8080/swagger-ui.html，显示界面如下：

4.常用注解介绍

@Api	表示该类是swagger资源，也就会处理成API
@ApiImplicitParam	请求参数
@ApiImplicitParams	请求参数集合，用于包装请求参数
@ApiModel	在使用对象的时候
@ApiModelProperty	model属性
@ApiOperation	方法描述
@ApiParam	额外的元数据操作参数
@ApiResponse	出现错误的响应信息
@ApiResponses	出现错误的响应信息集合，用于包装出现错误的响应信息
@Authorization	授权对资源使用或操作
@AuthorizationScope	Oauth2授权范围

具体的注解看官网，其余的就不叙述了。完整示例代码在QQ交流群中：springboot-swagger.zip

有兴趣的朋友可以加群探讨相互学习：

Spring Boot QQ交流群：599546061