SpringBoot集成Swagger，实现接口调试

一、swagger2 介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。随着前后端技术的日渐成熟，前后端的交互就只有接口了，前端请求接口获取数据，所以接口的格式化也就相当重要，有一个标准格式的接口文档在开发过程中是相当重要的，swagger就是这么一个在线的接口文档，在SpringBoot的集成之中也相当便利。

二、创建springboot项目

见springboot项目

（一） 添加swagger2依赖

<!--根据需要可以导入其他包，我就导入了lombok相关的包-->
<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>

（二）swagger2 配置

在Springboot启动类的同级目录下面创建一个config的包，然后创建一个配置Swagger2 的配置类。

package com.sgh.sbswagger;
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;
/**
 * 1. 使用 @Configuration 注解，标识这是一个配置类，项目启动的时候会自动调用加载，@EnableSwagger2 注解的作用是自动开启swagger2。
 *
 *  2. apiInfo() 方法里面的参数可以自己设定，在第一个方法中，我们除了可以根据接口所在的包对应生成接口文档还可以根据项目中是否有方法使用了 @ApiOperation注解来判断是否生成api文档。
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 指定构建api文档的详细信息的方法：apiInfo()
                .apiInfo(apiInfo())
                .select()
                // 指定要生成api接口的包路径  
                .apis(RequestHandlerSelectors.basePackage("com.sgh.sbswagger.controller"))//记得改成自己的哦
                //使用了 @ApiOperation 注解的方法生成api接口文档
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                //可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }
    /**
     * 设置api文档的详细信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 标题
                .title("Spring Boot集成Swagger2")
                // 接口描述
                .description("swagger")
                // 版本信息
                .version("1.0")
                // 构建
                .build();
    }
}

（三）controller 测试编写以及注解说明

上面我们配置好了swagger api生成的配置之后就可以编写测试的controller，创建一个与config同级的包controller，然后里面写一个TestController

package com.sgh.sbswagger.controller;
import com.sgh.sbswagger.entity.User;
import com.sgh.sbswagger.service.UserServiceUtils;
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.*;
/**
 * @RestController 相当于@Controller+@ResponseBody 注解，让标识的这个类返回json格式的数据。
 * 类上面加上@Api的注解，说明这个类要生成api文档，并给予描述。相当于可以根据这个类作为类别的划分。在类里面的方法加上@ApiOperation 注解 用来描述这个方法(接口)是用来干嘛的；
 * @ApiImplicitParam 注解是为了描述这个方法之中的参数。其中的name，value属性你应该知道。required 属性是标识在测试接口时，这个参数是否需要传，true为必须传，false为非必须。
 * @ApiImplicitParam之中的paramType是标识这个参数应该在哪去获取，常用的有以下几种
 * header-->放在请求头。请求参数的获取注解：@RequestHeader
 * query -->常用于get请求的参数拼接。请求参数的获取注解：@RequestParam
 * path -->(用于restful接口)-->请求参数的获取获取注解：@PathVariable
 * body -->放在请求体。请求参数的获取注解：@RequestBody
 * @ApiImplicitParam之中的dataType 是用来标识这个参数的类型，默认为String，如果是数组类型，需要加上allowMultiple=true，表示是数组类型的数据。也可以是自定义的对象类型。
 */
@Controller
public class UserController {
    @Autowired
    private UserServiceUtils userServiceUtils;
    @RequestMapping(value = "/getUserByName",method = RequestMethod.POST)
    //设置swagger属性
    @ApiOperation("/根据学生id获取学生信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query",dataType = "String"),
            @ApiImplicitParam(name = "age",value = "年龄",required = true,paramType = "query",dataType = "int")
    })
    public @ResponseBody  User getUserByName(@RequestParam String name){
        User userByName = userServiceUtils.getUserByName(name);
        return userByName;
    }
}

（四）创建entity类

package com.sgh.sbswagger.entity;
import io.swagger.annotations.ApiModel;
import lombok.Data;
import lombok.Getter;
import lombok.Setter;
@Data
@Getter
@Setter
@ApiModel("用户类")
public class User {
    private String name;
    private String addr;
    private Integer age;
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getAddr() {
        return addr;
    }
    public void setAddr(String addr) {
        this.addr = addr;
    }
    public Integer getAge() {
        return age;
    }
    public void setAge(Integer age) {
        this.age = age;
    }
}

（五）创建service

package com.sgh.sbswagger.service;
import com.sgh.sbswagger.entity.User;
import org.springframework.stereotype.Service;
import java.util.ArrayList;
import java.util.List;
@Service
public class UserServiceUtils {
    //此处就没有写入数据库
    public User getUserByName(String name){
        List<User> list = new ArrayList<>();
        for (int i = 0; i < 10; i++) {
            User u1 = new User();
            u1.setName("sgh"+1);
            u1.setAddr("重庆欢迎你"+i);
            u1.setAge(18);
            list.add(u1);
        }
        for (int i = 0; i < list.size(); i++) {
            if(list.get(i).getName()!=null && list.get(i).getName().equals(name)){
                return list.get(i);
            }
        }
        return null;
    }
}

（六）添加配置文件读取包的位置

@SpringBootApplication
@ComponentScan(basePackages = {"com.sgh.sbswagger"})//此处需调节配置文件路径
public class SbswaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SbswaggerApplication.class, args);
    }

}

三、接口测试

完成以上步骤，带你们看看swagger的界面如何，启动项目，浏览器输入localhost:8091/swagger-ui.html
如下：
结果：

四、swagger2使用说明：

@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
@ApiIgnore：使用该注解忽略这个API
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性

参考文章：https://blog.csdn.net/ligh_sqh/article/details/80325933 && https://www.cnblogs.com/youngdeng/p/12869109.html ，也遇到了一些其他问题，但都解决了。祝观看者们好运。