SpringMVC--Swagger2集成

已经有两个月没有更新啦，有不少东西都尚未整理出来，陆续会所有整理清晰再更新出来。

相信全部的后台开发人员都会写接口文档，并且也必须写接口文档，并且还必须条理清晰，负责就会被同事吐槽，并且接口变更，对应文档也要变更，特别是入职没有多久，尚未养成良好的文档编写习惯，极可能就会忘记编写或更新接口文档。因此为了解决这个烦恼,Swagger2应运而生。

1、什么是 Swagger？

Swagger是一款 RESTful 接口的文档在线自动生成+功能测试的功能插件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。接口的文档在线自动生成+测试，是否是很爽啊。接下来咱们就来看看它与SpringMVC的整合

2、Swagger2 怎么用？

一、添加包：

<!-- 2.8.0版本没有测试成功，这里采用2.7.0 -->
        <dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.7.0</version>
		</dependency>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.7.0</version>
		</dependency>

二、编写配置类：

package com.gy.spring.mvc.common.interceptor;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

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;

/**
 * TODO Swagger2配置类
 * Swagger2注解说明: https://blog.csdn.net/xiaojin21cen/article/details/78654652
 * @author geYang
 * @date 2018-04-16
 */
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
	
	@Bean
    public Docket customDocket() {
		return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select().apis(RequestHandlerSelectors.basePackage("com.gy.spring.mvc.controller"))
        .paths(PathSelectors.regex("/user/.*")) // "/.*" 为全部接口
        .build();
        
    }
	
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        		.title("API接口文档")
        		.description("API接口文档描述")
        		.version("0.0.1")
        		.contact(new Contact("geYang", "https://my.oschina.net/u/3681868/home", "572119197@qq.com"))
//        		.termsOfServiceUrl("URL的服务条款")
//        		.license(null)
//        		.licenseUrl(null)
        		.build();
    }
	
}

三、Spring容器声明（spring-mvc.xml）:

<!-- 放行SwaggerUI的静态文件 -->
	<mvc:default-servlet-handler />
	
	<!-- 声明SwaggerConfig到容器 -->
	<bean class="com.gy.spring.mvc.common.interceptor.SwaggerConfig"/>

四、接口注解配置（Controller）：

package com.gy.spring.mvc.controller;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.gy.spring.mvc.entity.User;
import com.gy.spring.mvc.service.RedisService;
import com.gy.spring.mvc.service.UserService;

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



/**
 * TODO 用户控制器
 * @author geYang
 * @date 2018-04-16
 */
@RestController
@RequestMapping("user")
@Api(description="用户相关API")
public class UserController {
	@Autowired
	private RedisService redisService;
	
	@Autowired
	private UserService userService;
	
	/**
	 * TODO 用户列表
	 * @return
	 * @author geYang
	 * @date 2018-04-16 11:37
	 */
	@ApiOperation(value="用户列表", notes="获取全部用户列表")
	@RequestMapping(value="list",method=RequestMethod.GET)
	public Object list() {
		String userList = redisService.get("user:list");
		if(userList==null) {
			userList = userService.selectList(null).toString();
			redisService.set("user:list", userList);
		}
		return userList;
	}
	
	/**
	 * TODO 用户详情
	 * @param id
	 * @return
	 * @author geYang
	 * @date 2018-04-16 11:37
	 */
	@ApiOperation(value="用户详情", notes="获取用户详情")
	@ApiImplicitParams({
		@ApiImplicitParam(name="id",value="用户ID",required=true,paramType="path",dataType="int"),
	})
	@RequestMapping(value="get/{id}",method=RequestMethod.GET)
	public Object get(@PathVariable("id") int id) {
		String userStr = redisService.get("user:"+id);
		if (userStr==null) {
			User user = userService.selectById(id);
			if(user!=null) {
				userStr = user.toString();
				redisService.set("user:"+id, userStr);
			}
		}
		return userStr;
	}
	
	/**
	 * TODO 用户添加
	 * @param user
	 * @return
	 * @author geYang
	 * @date 2018-04-16 11:37
	 */
	@ApiOperation(value="用户添加", notes="添加用户信息")
	@RequestMapping(value="add",method=RequestMethod.POST)
	public Object add(User user) {
		return userService.insert(user);
	}
	
	/**
	 * TODO 用户更新
	 * @param user
	 * @return
	 * @author geYang
	 * @date 2018-04-16 11:36
	 */
	@ApiOperation(value="用户更新", notes="更新用户信息")
	@RequestMapping(value="update",method=RequestMethod.PUT)
	public Object update(User user) {
		redisService.del("user:"+user.getId());
		return userService.updateById(user);
	}
	
	/**
	 * TODO 用户删除
	 * @param id
	 * @return
	 * @author geYang
	 * @date 2018-04-16 11:37
	 */
	@ApiOperation(value="用户删除", notes="删除用户详情")
	@RequestMapping(value="del/{id}",method=RequestMethod.DELETE)
	public Object del(
			@ApiParam(name = "id", value = "用户ID", required = true)
			@PathVariable("id") int id) {
		redisService.del("user:"+id);
		return userService.deleteById(id);
	}
	
	/**
	 * TODO 回滚测试
	 * @throws Exception
	 * @author geYang
	 * @date 2018-04-16 11:38
	 */
	@ApiOperation(value="回滚测试", notes="事务回滚测试")
	@RequestMapping(value="test",method=RequestMethod.GET)
	public void test() throws Exception {
		userService.test();
	}
	
	/**
	 * TODO 缓存测试
	 * @return
	 * @author geYang
	 * @date 2018-04-16 11:38
	 */
	@ApiOperation(value="缓存测试", notes="MyBatis二级缓存测试")
	@RequestMapping(value="testCache",method=RequestMethod.GET)
	public Object testCache(){
		userService.selectById(1);
		userService.selectById(1);
		return userService.selectById(1);
	}
}

到这里就完成了简单的集成配置，能够进行测试了： http://localhost:8080/mvc/swagger-ui.html

项目源码： https://gitee.com/ge.yang/spring-demo/tree/master/spring-mvc