springboot整合Swagger2的使用

Swagger2相较于传统Api文档的优点

手写Api文档的几个痛点：

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。

接口返回结果不明确

不能直接在线测试接口，通常需要使用工具，比如postman

接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

可以直接使用Swagger editor编写接口文档，我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

依赖文件


io.springfox
springfox-swagger2
2.6.1


io.springfox
springfox-swagger-ui
2.6.1


配置类

package com.boss.hr.train.fishkkmybatis.config;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @author fishkk
* @version 1.0.0
* @since
*/
@Configuration
public class Swagger2Configuration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.boss.hr.train.fishkkmybatis.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("fishkk的Swagger")
.version("1.0")
.build();
}
}

在启动函数出天价@EnableSwagger2，到这里就可以正常的使用Swagger2 了

Swagger2 的具体使用

package com.boss.hr.train.fishkkmybatis.controller;
import com.boss.hr.train.fishkkmybatis.annotation.Logg;
import com.boss.hr.train.fishkkmybatis.entity.Dictionary;
import com.boss.hr.train.fishkkmybatis.entity.Result;
import com.boss.hr.train.fishkkmybatis.enums.DictionaryEnum;
import com.boss.hr.train.fishkkmybatis.exception.BaseException;
import com.boss.hr.train.fishkkmybatis.service.impl.DictionaryServiceImpl;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import javax.validation.Valid;
import java.util.List;
import java.util.Random;
import java.util.concurrent.TimeUnit;
/**
* @author fishkk
* @version 1.0.0
* @since 2019/7/27
*/
@RestController
@RequestMapping(value = "/dic")
@CrossOrigin
public class DictionaryController {
/**
* Redis 缓存
*/
@Resource
private RedisTemplate redisTemplate;
@Resource
private DictionaryServiceImpl dictionaryService;
private List list;
/**
* 创建字典实体
* @author fishkk
* @since 2017/7/25
* @param dictionary 字典实体
* @return Dictionary 放回创建的字典实体
*/
@ApiOperation(value="创建字典", notes="根据Dictionary对象创建字典")
@ApiImplicitParam(name = "dictionary", value = "字典详细实体dictionary", required = true, dataType = "Dictionary")
@PostMapping(value = "/insert")
public Result insertDic(@Valid Dictionary dictionary, BindingResult bindingResult){
if (bindingResult.hasErrors()){
return Result.error(DictionaryEnum.ERROR_INPUT);
}
dictionaryService.insert(dictionary);
return Result.success(dictionary);
}
/**
* 根据主键查找字典
* @author fishkk
* @since 2019/7/25
* @param id 主键id
* @return dictionary查找到的实体对象
*/
@ApiOperation(value = "获取字典信息",notes = "根据id获取字典信息")
@ApiImplicitParam(name = "id",value = "字典id",required = true, dataType = "Long", paramType = "path")
@GetMapping(value = "/dic")
public Result findById(@RequestParam(value = "id") Integer id){
if (list == null){
list = dictionaryService.selectAll();
for (Dictionary x:list) {
long time = new Random().nextInt(10);
redisTemplate.opsForValue().set(x.getCategoryId(),x,12,TimeUnit.HOURS);
}
}
if (redisTemplate.opsForValue().get(id) != null){
return Result.success(redisTemplate.opsForValue().get(id));
}
redisTemplate.opsForValue().set(id,dictionaryService.selectByPrimaryKey(id),12,TimeUnit.HOURS);
return Result.success(dictionaryService.selectByPrimaryKey(id));
}
/**
* 根据主键删除字典
* @author fishkk
* @since 2019/7/25
* @param id 字典主键
*/
@ApiOperation(value = "根据id删除单个字典表",notes = "根据id删除字典")
@ApiImplicitParam(name = "id",value = "用户id",required = true, dataType = "Long", paramType = "path")
@GetMapping(value = "/remove/{id}")
public Result deleteById(@PathVariable("id") Integer id){
dictionaryService.deleteByPrimaryKey(id);
return Result.success(null);
}
/**
* 更新字典对象
* @author fishkk
* @since 2019/7/26
* @param dictionary 修改过的字典对象
*/
@ApiOperation(value="更新字典", notes="根据Dictionary更新对应的字典")
@ApiImplicitParam(name = "dictionary", value = "字典详细实体dictionary", required = true, dataType = "Dictionary")
@PostMapping(value = "/updata")
public Result updata(@Valid Dictionary dictionary, BindingResult bindingResult){
if (bindingResult.hasErrors()){
return Result.error(DictionaryEnum.ERROR_INPUT);
}
dictionaryService.updateByPrimaryKey(dictionary);
return Result.success(null);
}
/**
* 根据字典名查询
* @author fishkk
* @since 2019/7/28
* @param name 字典名
*/
@GetMapping(value = "/get/{name}")
public Result findByName(@PathVariable("name") String name ){
return Result.success(dictionaryService.findByName(name));
}
/**
* 根据字典类型查询
* @author fishkk
* @since 2019/7/28
* @param type 字典类型
*/
@GetMapping(value = "/gettype/{type}")
public Result findByType(@PathVariable("type") String type){
return Result.success(dictionaryService.findByType(type));
}
/**
* 获取全部对象
* @author fishkk
* @since 2019/7/28
*/
@Logg
@GetMapping(value = "/getall")
public Result findByType(){
//throw new BaseException(DictionaryEnum.NOT_FOUND);
return Result.success(dictionaryService.selectAll());
// Float a = null;
// Float b = Float.intBitsToFloat(11);
// System.out.println(a + b);
// return null;
}
}

启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html

可以看到上诉类似的结果，我的项目启动太麻烦了含SpringCloud 就不展示了。

Swagger2的注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用


• @ApiOperation：描述一个类的一个方法，或者说一个接口


• @ApiParam：单个参数描述


• @ApiModel：用对象来接收参数


• @ApiProperty：用对象接收参数时，描述对象的一个字段


• @ApiResponse：HTTP响应其中1个描述


• @ApiResponses：HTTP响应整体描述


• @ApiIgnore：使用该注解忽略这个API


• @ApiError ：发生错误返回的信息


• @ApiImplicitParam：一个请求参数


• @ApiImplicitParams：多个请求参数