SpringBoot集成Swagger

前言

作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。

对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

接着我们来讲解如何在SpringBoot项目中集成和使用Swagger 

1. SpringBoot集成Swagger

1、安装Swagger依赖，在Pom.xml文件中设置如下代码，在Maven中重新加载

<!--        Swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
<!--        Swagger-UI -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、添加Swagger配置类 新建配置类包ConfigClass包，创建SwaggerConfig配置类文件进行Swagger配置

package com.example.demo.configclass;

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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的，代表swagger2
//  .groupName("分布式任务系统") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo()) // 用于生成API信息
                .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 用于指定扫描哪个包下的接口
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();
    }

    /**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX项目API") // 可以用来自定义API的主标题
                .description("XX项目SwaggerAPI管理") // 可以用来描述整体的API
                .termsOfServiceUrl("") // 用于定义服务的域名
                .version("1.0") // 可以用来定义版本。
                .build(); //
    }
}

此时运行项目如果报错可能是Spring-boot-start-parent版本问题 更改版本为2.5

通过配置文件可以配置：用于扫描的控制器所在位置、项目名称、项目介绍、项目服务域名 、项目版本等信息；

如果访问locahost:8080/swagger-ui.html访问不到 报错：No mapping for GET /swagger-ui.html

则需要添加mvcconfig类

package com.example.demo.configclass;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

配置完成后通过http://localhost:8080/swagger-ui.html即可访问到Swagger

2. Swagger常用注解的使用 

//@Api()用于类 表示标识这个类是swagger的资源 

@Api(tags="商品品牌管理相关操作")     //接口名称


//@ApiOperation()用于方法 表示一个http请求的操作 

@ApiOperation(value="删除商品")


//实例
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
     @ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点") 
     @GetMapping("/getUserInfo") 
     public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) { 
        // userService可忽略，是业务逻辑 
        User user = userService.getUserInfo(); 
        return user; 
    } 
}


//@ApiParam()用于方法，参数，字段说明 表示对参数的添加元数据（说明或是否必填等） 

    public User searchByKeyWord(@ApiParam(name="userName",value="关键字",required=true) @RequestParam("userName") String userName){
        return userService.getUserByName(userName);
    }

//@ApiModel()用于类 表示对类进行说明，用于参数用实体类接收 

    @ApiModel(value="",description="");

//@ApiModelProperty()用于方法，字段表示对model属性的说明或者数据操作更改 

//@ApiIgnore()用于类，方法，方法参数表示这个方法或者类被忽略 

//@ApiImplicitParam() 用于方法 表示单独的请求参数 

//@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

3. Swagger配置请求头信息（常用语传递token参数）

有时候我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。

    @Bean
    public Docket docket() {
        // 设置请求头
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(new ParameterBuilder()
                .name("token") // 字段名
                .description("token") // 描述
                .modelRef(new ModelRef("string")) // 数据类型
                .parameterType("header") // 参数类型
                .defaultValue("default value") // 默认值：可自己设置
                .hidden(true) // 是否隐藏
                .required(false) // 是否必须
                .build());

        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("mike") // 修改组名为 "mike"
                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
                )
                .paths(PathSelectors
                        .any() // 满足条件的路径，该断言总为true
                )
                .build()

                // 添加请求头参数
                .globalOperationParameters(parameters);
    }

参考文章：Swagger-的使用 +Swagger-UI添加请求头_swagger添加请求头-CSDN博客