已经有两个月没有更新啦，有很多东西都还没有整理出来，陆续会全部整理清晰再更新出来。
相信所有的后台开发人员都会写接口文档，而且也必须写接口文档，而且还必须条理清晰，负责就会被同事吐槽，而且接口变动，对应文档也要变动，特别是入职没有多久，还没有养成良好的文档编写习惯，很可能就会忘记编写或更新接口文档。所以为了解决这个烦恼,Swagger2应运而生。
一、什么是 Swagger？
Swagger是一款 RESTful 接口的文档在线自动生成+功能测试的功能插件。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。接口的文档在线自动生成+测试，是不是很爽啊。接下来我们就来看看它与SpringMVC的整合
二、Swagger2 怎么用？
1、添加包：
<!-- 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>2、编写配置类：
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", "[email protected]"))
// .termsOfServiceUrl("URL的服务条款")
// .license(null)
// .licenseUrl(null)
.build();
}
}
3、Spring容器声明（spring-mvc.xml）:
<!-- 放行SwaggerUI的静态文件 -->
<mvc:default-servlet-handler />
<!-- 声明SwaggerConfig到容器 -->
<bean class="com.gy.spring.mvc.common.interceptor.SwaggerConfig"/>4、接口注解配置（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