springboot 整合Swagger2的使用

时间 2019-11-09

标签 springboot 整合 swagger2 swagger 使用栏目 Spring 繁體版

原文原文链接

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

手写Api文档的几个痛点：

文档须要更新的时候，须要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，一般须要使用工具，好比postman
接口文档太多，很差管理
Swagger也就是为了解决这个问题，固然也不能说Swagger就必定是完美的，固然也有缺点，最明显的就是代码移入性比较强。
能够直接使用Swagger editor编写接口文档，咱们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。
依赖文件html

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

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
web

能够看到上诉相似的结果，个人项目启动太麻烦了含SpringCloud 就不展现了。redis

Swagger2的注解

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

@Api：修饰整个类，描述Controller的做用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应总体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数