SpringBoot整合Swagger3环境搭建

一、概述

编写和维护开发接口中的文档，其为一个规范、完整和统一的接口文档维护规范/标准，用于生成、描述、调用和可视化接口文档的web服务；

二、Springboot整合swagger3环境搭建

1.导入swagger依赖

  <!-- swagger3--><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId></dependency><!-- 防止进入swagger页面报类型转换错误，排除3.0.0中的引用，手动增加1.6.2版本 --><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.6.2</version></dependency>

2.yml配置

# Swagger配置
swagger:# 是否开启swaggerenabled: true# 请求前缀
#  pathMapping: /dev-apipathMapping: /dev-api

3.Swagger配置类

package com.ruoyi.web.core.config;import com.ruoyi.common.config.RuoYiConfig;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;
import java.util.List;/*** Swagger2的接口配置* * @author ruoyi*/
@Configuration  //标明是配置类
public class SwaggerConfig
{/** 系统基础配置 */@Autowiredprivate RuoYiConfig ruoyiConfig;/** 是否开启swagger */@Value("${swagger.enabled}")private boolean enabled;/** 设置请求的统一前缀 */@Value("${swagger.pathMapping}")private String pathMapping;/*** 创建API*/@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.OAS_30)// 是否启用Swagger.enable(enabled)// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）.apiInfo(apiInfo())// 设置哪些接口暴露给Swagger展示.select()// 扫描所有有注解的api，用这种方式更灵活.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 扫描指定包中的swagger注解// .apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))// 扫描所有 .apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build()/* 设置安全模式，swagger可以设置访问token */.securitySchemes(securitySchemes()).securityContexts(securityContexts()).pathMapping(pathMapping);}/*** 安全模式，这里指定token通过Authorization头请求头传递*/private List<SecurityScheme> securitySchemes(){List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));return apiKeyList;}/*** 安全上下文*/private List<SecurityContext> securityContexts(){List<SecurityContext> securityContexts = new ArrayList<>();securityContexts.add(SecurityContext.builder().securityReferences(defaultAuth()).operationSelector(o -> o.requestMappingPattern().matches("/.*")).build());return securityContexts;}/*** 默认的安全上引用*/private List<SecurityReference> defaultAuth(){AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;List<SecurityReference> securityReferences = new ArrayList<>();securityReferences.add(new SecurityReference("Authorization", authorizationScopes));return securityReferences;}/*** 添加摘要信息*/private ApiInfo apiInfo(){// 用ApiInfoBuilder进行定制return new ApiInfoBuilder()// 设置标题.title("标题：越越管理系统_接口文档")// 描述.description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")// 作者信息.contact(new Contact(ruoyiConfig.getName(), null, null))// 版本.version("版本号:" + ruoyiConfig.getVersion()).build();}
}

三、Swagger常用注解配置

3.1 @ApiModel与@ApiModelProperty 实体描述

1. @ApiModel(value="实体类名称",description="实体类描述")：标注在实体类上，用于对实体类进行描述说明
2. @ApiModelProperty(value="简要描述",hidden=false,dataType="数据类型")：标注于实体类属性或方法上，用于对实体类的属性或方法进行描述说明。其中hidden表示是否隐藏该属性（默认为false）

3.2 @Api(tags = “接口模块类描述说明”)

@Api(tags = "接口模块类描述说明")：该注解标注在接口模块类上，用于对接口模块类进行描述说明

3.3 @ApiOperation 接口方法描述

@ApiOperation(value="接口方法简要说明",notes="接口方法详细描述",response=Class<T>)：该注解标注在接口模块类的接口方法上，用于对接口方法进行描述说明。其中notes字段可以插入HTML标签，response字段表示该方法的返回值类型。

3.4 @ApiImplicitParams与@ApiImplicitParam 参数描述

1. @ApiImplicitParams(list=[ ])：该注解作用在接口方法上，是ApiImplicitParam的列表
2. @ApiImplicitParam(name="参数名称",value = "参数说明",defaultValue = "参数默认值",dataType = "数据类型")：该注解作用于ApiImplicitParams列表内，用于对方法上的参数进行描述说明。

四、Swagger接口文档导出/更改UI

Swagger原生官方依赖不提供文档导出功能，只能网页在线查看。所以要实现接口文档导出，我们可以通过以下两种方式（注意url拦截器放行）：整合第三方Swagger-UI界面提供的文档导出功能（主要）bootstrap-UILayui-UImg-UI
整合第三方导出插件，实现文档导出功能

1. bootstrap-UI

注意访问地址为：http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 访问地址 /doc.html-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version>
</dependency>

2. knife4j

knife4j是bootstrap-UI的升级版。相比bootstrap-UI来说，knife4j功能更加完善和强大，并且其starter中已经封装了springfox，我们无需再次引入。官网文档地址：https://doc.xiaominfo.com/knife4j/

五、Swagger整合常见问题

1. 权限管理中的拦截问题在Shiro或SpringSecurity权限管理框架中，使用Swagger时访问文档主页会被拦截，因此我们需要配置放行相关swagger资源的访问请求。下面以Shiro整合为例：