Springboot系列（一）使用Swagger2构建API文档

Swagger2的作用：
    作为一个程序员平时接触烦的就是写开发文档，本来写功能就很多了还要写无关的。但是又必须写，自己以后要看，同时也要看。所以我们使用Swagger2来减少我们的工作量。

Swagger2的使用：

1. 引入对应的jar包(这里注意版本要和spring版本适应)

      <!--swagger2依赖，构建API文档-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.创建一个Swagger2配置类 （注意在启动类上加上【@EnableSwagger2】注解）
SwaggerConfig.java

package com.qsmm.qsmm_admin.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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * \* Created with IntelliJ IDEA.
 * \* User: 一颗小土豆
 * \* Date: 2020/3/7
 * \* Time: 10:09
 * \*  Swagger2接口插件的配置文件
 * \* http://localhost:8088/swagger-ui.html
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qsmm.qsmm_admin.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("API文档")
                .description("API使用即参数定义")
                .termsOfServiceUrl("https://blog.csdn.net/weixin_43064399")
                .contact("ZZP")
                .version("0.1")
                .build();
    }
}

现在就已经配置好了，我们打开项目看一看，发现已经创建好默认的AP了

我们发现全是接口名，这怎么找，没有接口描述。

我们可以给每个接口添加注解，进行详细的描述
在controller中添加注解

package com.qsmm.qsmm_admin.controller;

import com.qsmm.qsmm_admin.Utils.MessageUtil;
import com.qsmm.qsmm_admin.Utils.RedisUtil;
import com.qsmm.qsmm_admin.entity.TdFamilyInfo;
import com.qsmm.qsmm_admin.service.TdFamilyInfoService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import java.text.MessageFormat;
import java.util.List;
import java.util.Map;

/**
 * \* Created with IntelliJ IDEA.
 * \* User: 一颗小土豆
 * \* Date: 2020/3/7
 * \* Time: 9:50
 * \
 */
@Controller
@RequestMapping("/family")
public class TdFamilyInfoController {

    @Autowired
    RedisUtil redisUtil;

    @Autowired
    TdFamilyInfoService familyInfoService;

    @ApiOperation(value = "查询家庭成员信息",notes = "根据月嫂的Id")
    @ApiImplicitParam(name = "nurseId",value = "月嫂id",required = true,dataType = "Integer")
    @GetMapping(value ="/family_list/{nurseId}")
    @ResponseBody
    public List<TdFamilyInfo> selectAllByNurseId(@PathVariable("nurseId") Integer nurseId){

        if (redisUtil.get("family"+nurseId)!=null){
            return (List<TdFamilyInfo>) redisUtil.get("family"+nurseId);
        }
        List<TdFamilyInfo> tdFamilyInfos = familyInfoService.selectAllbyNurseId(nurseId);
        redisUtil.set("family"+nurseId,tdFamilyInfos,8640);
        return tdFamilyInfos;
    }

    @ApiOperation(value = "查询家庭成员信息",notes = "根据主键Id")
    @ApiImplicitParam(name = "id",value = "主键id",required = true,dataType = "Integer")
    @GetMapping(value ="/getflimly/{id}")
    @ResponseBody
    public Map<String,Object> getFlimlyById(@PathVariable("id") Integer id){
        TdFamilyInfo familyInfo = familyInfoService.selectByPrimaryKey(id);
        return MessageUtil.getSuccessResult("获取数据成功",familyInfo);
    }


    @ApiOperation(value = "删除家庭成员信息",notes = "根据主键Id")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "主键id",required = true,dataType = "Integer"),
            @ApiImplicitParam(name = "nurseId",value = "月嫂id",required = true,dataType = "Integer")
    })
    @RequestMapping(value ="/delete_flimly",method = RequestMethod.POST)
    @ResponseBody
    public Map<String,Object> deleteFlimlyById(@RequestParam("id") Integer id,@RequestParam("nurseId") Integer nurseId){
        System.out.println("id："+id+",nurseId"+nurseId);
        familyInfoService.deleteByPrimaryKey(id);
        redisUtil.del("family"+nurseId);
        return MessageUtil.getSuccessResult("删除成功",null);
    }

    @ApiOperation(value = "修改家庭成员信息",notes = "根据主键Id，使用家庭成员对象进行修改")
    @ApiImplicitParam(name = "familyInfo",value = "家庭成员对象",required = true,dataType = "TdFamilyInfo")
    @PutMapping(value ="/del_add_flimly")
    @ResponseBody
    public Map<String,Object> updateFlimlyById(TdFamilyInfo familyInfo){
        System.out.println(familyInfo);
        try {
            if (familyInfo.getId()!=null){
                System.out.println("修改家庭数据");
                familyInfo.setState(1);
                familyInfoService.updateByPrimaryKey(familyInfo);
                redisUtil.del("family"+familyInfo.getNurseId());
                return MessageUtil.getSuccessResult("修改成功",null);
            }else {
                System.out.println("添加家庭数据");
                familyInfo.setState(1);
                familyInfoService.insert(familyInfo);
                redisUtil.del("family"+familyInfo.getNurseId());
                return MessageUtil.getSuccessResult("添加成功",null);
            }

        }catch (Exception e){
            return MessageUtil.getSuccessResult("出现未知的错误",e.toString());
        }
    }


}

通过一下注解，进行API的自定义描述

@ApiOperation(value = “删除家庭成员信息”,notes = “根据主键Id”)

这里的值是接口的名称或描述

@ApiImplicitParam参数的描述

@ApiImplicitParams 多个参数时使用，它里面可以包含多个@ApiImplicitParam

我们点击去可以看到，接口接受的参数值类型，和返回值