【每天学一点-01】在SpringBoot项目中使用Swagger2

今天在做毕设的时候，发现在前后端分离的情况下，去调用接口数据时很不方便，然后回想过去，和同学一起做项目的时候，他负责后端，我负责前端，当时调用他的弄好的接口可以说是非常方便，主要是可以通过UI页面直接对接口数据进行测试，清楚接口的返回数据类型、状态码、请求地址等等。今天就来学习一下这个接口文档生成工具Swagger。

一、首先介绍一下Swagger

Swagger是一款RESTFUL（RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。）接口的文档在线自动生成和功能测试的工具。我觉得Swagger可以缓解前端和后端人员产生肢体冲突>_<

二、结合SpringBoot项目的使用

1、首先在项目Maven中添加Swagger的依赖

疑惑1：springfox是什么？用来干什么的？

回答：springfox由swagger-springmvc发展而来，springfox是集成swagger的生态，springfox是扫描注解的代码提取信息自动生成API文档的工具，通过Swagger-UI来呈现API文档，相对于spring将swagger结合自身推出的工具，spring-swagger和swagger一样，前者更适用于Spring项目。

疑惑2：swagger-ui是什么？用来干什么的？

回答：swagger-ui就是接口文档的界面，用来展示接口数据、测试接口数据、显示描述接口信息等等。以前要测试接口需要去浏览器地址栏输入或者手写HTML页面，通过表单提交访问，其中如果还有请求参数的话，GET还需要&xx=xx?xx=xx，POST请求还需要表单等等，总而言之非常麻烦，有了swagger-ui，不用手动搭建这些提交必备的条件，直接在UI页面输入参数点点点就可以看见结果了。

【pom.xml配置文件】

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

注意：这里使用的是Swagger-2.9.2版本，SpringBoot-2.5.6版本以上会报错，需要使用SpringBoot-2.5.6或者以下版本。（我是使用的是SpringBoot-2.5.6哒）

2、在项目中创建一个swagger2配置类

话不多说直接附上代码

@Configuration //配置类
@EnableSwagger2 //开启Swagger的自动配置
public class Swagger2UiConfiguration{

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) //添加Swagger信息，在下面哦
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cn.edu.hziee.controller")) //接口AIP路径，也就是控制器所在包路径
                .paths(PathSelectors.any()) //选择路径
                .build(); //构建，出发！
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo(){
        //作者信息（名字，博客地址，邮箱）
        Contact contact = new Contact("Rootkital","https://www.cnblogs.com/Rootkital/","bbang98@foxmail.com");
        return new ApiInfo(
                "健身房会员管理系统接口文档", //文档说明
                "接口文档", 
                "1.0.0", //版本
                "https://www.cnblogs.com/Rootkital/",
                contact, //联系人
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", //协议
                new ArrayList<VendorExtension>());
        }
    }

3、在controller中使用注解

请求类注解:

@API标识Swagger识别类

@API放在@Controller注解并列的请求类

@ApidOperation 方法说明

请求方法注解:

@ApilmplicitParams 用于指定单个参数的说明

@ApilmplicitParam 方法参数说明

@ApiResponses 用于指定单个参数的说明

@ApiResponse 方法返回值的说明

swagger2配置类写好后，接下来就是将注解写在controller类中，话不多说，直接上代码

package com.cn.edu.hziee.controller;

import com.cn.edu.hziee.entity.Member;
import com.cn.edu.hziee.service.MemberService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

//@Api:请求类注解
@Api(value = "",tags="MemberController",description="会员CRUD",hidden = true) //tags：接口命名，description：描述，hideen：是否隐藏
@ApiResponses(value = { //接口返回信息
        @ApiResponse(code = 200, message = "success!"), //code:状态码，message:状态码描述
        @ApiResponse(code = 401, message = "not authorized!"),
        @ApiResponse(code = 403, message = "forbidden!"),
        @ApiResponse(code = 404, message = "not found!")
})
@CrossOrigin //全跨域
@RequestMapping("/member")
@Controller
public class MemberController {

    @Autowired
    MemberService memberService;

    /*选项模糊查询*/
    @ApiOperation(value = "模糊查询会员，以列表形式返回会员信息", //@ApiOperation:请求方法注解
            responseContainer = "Map", //返回类型
            response = Member.class, //返回参数对应的实体类Bean
            tags = "getMembersByKey") //请求方法名

    @PostMapping
    @ResponseBody //@RequestParam：请求的参数
    public List<Member> getMemberListByKey(@RequestParam("searchOption")String searchOption,@RequestParam("searchKey")String searchKey){
        List<Member> members = new ArrayList<Member>();
        members = memberService.searchMember("member_" + searchOption,searchKey);
        return members;
    }

    /*获取全部会员*/
    @RequestMapping(value = "getMemberList",method = RequestMethod.POST)
    @ResponseBody
    public Map<String, Object> getMemberList(HttpServletRequest request){
        Map<String,Object> map = new HashMap<>();
        List<Member> members = new ArrayList<Member>();
        members = memberService.getMemberList();
        map.put("code",0);
        map.put("msg","获取全部会员");
        map.put("count",members.size());
        map.put("data",members);
        return map;
    }
}

4、在实体类中使用注解

请求对象注解:

@ApiModel标识Swagger识别的JavaBean，说明JavaBean的用途

@ApiModel放在JavaBean的类定义上

@ApiModelProperty标识JavaBean的属性上面，说明此属性的含义

在实体类/Bean/POJO中使用注解，代码如下

@ApiModel(description = "会员实体类",value = "会员对象") //description:描述，value:字段说明
public class Member {
    /*
    * 编号；主键
    * */
    @ApiModelProperty(name="member_id",required = true,value = "编号；主键") //name：字段说明，name:名称，required:是否必填
    private int member_id;

}

5、运行SpringBoot项目，访问swagger-ui

地址：http://localhost:8080/swagger-ui.html

5.1、页面显示如下