springboot 整合Swagger2的使用

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

手写Api文档的几个痛点：

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

接口返回结果不明确

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

接口文档太多，不好管理

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

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

依赖文件

<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>

配置类

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<Dictionary> 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：多个请求参数