SpringBoot集成swagger实例分析
一.接口文档概述swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具，在前后端开发之前，后端要先出接口文档，前端根据接口文档来进行项目的开发，双方开发结束后在进行联调测试。所以接口文档其实就是开发之前双方之间的一种约定。通常接口文档分为离线的和实时的。离线的接口文档工具有：word(相当于没说)，YAPI,小幺鸡等，这种文档需要程序员在上面编写，也一般具备接口测试功能。通常是由开发人员先在离线接口文档上编写信息，然后交给前端人员参照开发。最大的弊端是当我们的接
一. 接口文档概述
swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具，在前后端开发之前，后端要先出接口文档，前端根据接口文档来进行项目的开发，双方开发结束后在进行联调测试。
所以接口文档其实就是开发之前双方之间的一种约定。通常接口文档分为离线的和实时的。离线的接口文档工具有： word(相当于没说)， YAPI, 小幺鸡等，这种文档需要程序员在上面编写，也一般具备接口测试功能。通常是由开发人员先在离线接口文档上编写信息，然后交给前端人员参照开发。最大的弊端是当我们的接口程序发生变动时，需要回过头来维护上面的内容，很麻烦，是真的麻烦。
实时接口文档就是可以根据我们的代码来自动生成相应的接口文档，优点就是我们的代码发生变化时，生成的接口文档也会自动更新，无需我们关注修改，主需要按时发布即可。但是由于是根据代码自动生成的，所以最大的弊端就是代码侵入性强，需要我们在项目代码中集成生成接口文档的相关代码。实时接口文档现在的方案有很多，但是swagger还是其中比较有影响力的一个。
二. SpringBoot集成swagger2
官网地址： swagger.io 当然，官网都是英文的，看起来还是比较麻烦的。建议大家直接按照我的步骤来，还是很简单的。
同时在说一点： swagger分为swagger2 和swagger3两个常用版本。二者区别不是很大，主要对于依赖和注解进行了优化。swagger2需要引入2个jar包，swagger3只需要一个，用起来没有什么大的区别。下面以swagger2为例。
2.1 引入依赖
io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2
2.2 引入配置
首先需要添加一个注解 ： @EnableSwagger2。 这个注解我们可以添加到SpringBoot的启动类上，也可以自定义一个配置类，放到上面。添加了这个注解以后，就代表我们已经在项目中开启了Swagger的功能。
我们采用第二种方式，自己定义一个配置类，正好还可以添加一个Docket配置。 所谓Docket配置，就是一组(一个项目或一个版本)接口文档的配置，比如设置名称， 联系人等等。
我们在config文件夹下，添加一个SwaggerConfig类。
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 设置多个：
*
* @Bean
* public Docket appApi() {
*
* List pars = new ArrayList<>();
* ParameterBuilder token = new ParameterBuilder();
* token.name("token").description("用户令牌").modelRef(new ModelRef("string")).parameterType("header").required(false)
* .build();
* pars.add(token.build());
*
* return new Docket(DocumentationType.SWAGGER_2).select().paths(regex("/app/.*")).build()
* .globalOperationParameters(pars).apiInfo(pdaApiInfo()).useDefaultResponseMessages(false)
* .enable(enableSwagger)
* .groupName("appApi");
*
* }
*
* @Bean
* public Docket adminApi() {
*
* List pars = new ArrayList<>();
* ParameterBuilder token = new ParameterBuilder();
* token.name("token").description("用户令牌").modelRef(new ModelRef("string")).parameterType("header").required(false)
* .build();
* pars.add(token.build());
* return new Docket(DocumentationType.SWAGGER_2).select().paths(regex("/admin/.*")).build()
* .globalOperationParameters(pars).apiInfo(pdaApiInfo()).useDefaultResponseMessages(false)
* .enable(enableSwagger)
* .groupName("adminApi");
*
* }
*
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.lsqingfeng.action.swagger.controller")).paths(PathSelectors.any())
.build().globalOperationParameters(setHeaderToken());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("action-swagger").description("swagger实战").termsOfServiceUrl("")
.version("1.0").build();
}
/**
* @Description: 设置swagger文档中全局参数
* @param
* @Date: 2020/9/11 10:15
* @return: java.util.List
*/
private List setHeaderToken() {
List pars = new ArrayList<>();
ParameterBuilder userId = new ParameterBuilder();
userId.name("token").description("用户TOKEN").modelRef(new ModelRef("string")).parameterType("header")
.required(true).build();
pars.add(userId.build());
return pars;
}
} 上面就是一个配置案例， 还设置了一个setToken方法，代表生成文档的所有接口中，都要包含一个header类型的token参数。
2.3 给Controller 添加注解
我们接口文档的直接描述主要就是在Controller这一层，比如这个接口的功能，参数的名称，返回值的名称等。这些值我们都需要在Controller上通过给方法上，请求参数和返回参数上添加对应的注解，swagger才能帮我们生成相应的接口文档。这也就是我前面提到的对现有代码的侵入性。
我们来写一个案例。
首先先创建一个vo的包，里边写我们的请求和相应参数，使用JavaBean定义出请求和响应的数据结构。注意这里要添加相应的注解：
请求类：
package com.lsqingfeng.springboot.vo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* @className: SwaggerReqVO
* @description:
* @author: sh.Liu
* @date: 2022-03-22 19:19
*/
@Data
@ApiModel("创建Swagger请求参数")
public class SwaggerReqVO {
@ApiModelProperty("id")
private Integer id;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("性别")
private Integer gender;
}响应类：
package com.lsqingfeng.springboot.vo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
/**
* @className: SwaggerResVO
* @description:
* @author: sh.Liu
* @date: 2022-03-22 19:20
*/
@Data
@ApiModel("创建Swagger响应结果")
public class SwaggerResVO {
@ApiModelProperty("id")
private Integer id;
@ApiModelProperty("姓名")
private String name;
@ApiModelProperty("性别")
private Integer gender;
@ApiModelProperty("啥啥")
private String what;
}这里分别使用了 @ApiModel注解和 @@ApiModelProperty 注解定义了实体的名称和字段的名称，方便生成接口文档时展示。
再来看Controller:
package com.lsqingfeng.springboot.controller;
import com.lsqingfeng.springboot.vo.SwaggerReqVO;
import com.lsqingfeng.springboot.vo.SwaggerResVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
/**
* @className: SwaggerController
* @description: swagger 接口测试
* @author: sh.Liu
* @date: 2022-03-22 19:18
*/
@RestController
@RequestMapping("/swagger")
@Api(value = "用户接口", tags = {"用户接口"})
public class SwaggerController {
@ApiOperation("新增用户")
@PostMapping("save")
public String save(@RequestBody SwaggerReqVO req) {
return "success";
}
@GetMapping("getById")
@ApiOperation("根据条件查询用户")
public SwaggerResVO getById(@RequestBody SwaggerResVO req) {
return new SwaggerResVO();
}
}这里使用了@Api注解和 @ApiOperation注解分别标注了接口组名和接口的名称。现在我们启动项目。
发现报了这个错误。
上网查询原因说是SpringBoot2.6版本和Swagger2.9.2不兼容导致的。 也有人说是由于guava这个包的版本过低导致的。
我都分别试了一下，替换了guava的高版本依赖问题还是存在。
这个问题的主要原因确实是SpringBoot版本过高导致。如果你用的是SpringBoot2.5.x及之前版本是没有问题的。
Spring Boot 2.6.X使用PathPatternMatcher匹配路径，Swagger引用的Springfox使用的路径匹配是基于AntPathMatcher的。
所以要想解决，添加配置，将springBoot MVC的路劲匹配模式修改一下即可。
在springBoot配置文件中添加配置：
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER
如果是yml格式的配置文件：
再次启动问题解决。
访问地址： ip:端口号/swagger-ui.html
正常情况就可以看到我们的界面了。一会再说非正常情况。由于我们只给用户接口添加了注解，所有用户接口是可以直接观察中文文档的。而剩下的两个接口，由于没添加注解，所以都是以默认的形式展示的。
点开接口，我们可以看到接口中的想详细信息
点击model,可以看到字段的中文描述。点击 Try it out,就可以直接调试接口。同时注意接口中都让填一个token,这就是我们之前的设置成效了。
截止到目前其实swagger的集成就已经完毕了，主要就是根据我们的注解生成文档，并且可以在线调用调试。开发的时候，我们只需要把Controller这一层的请求和响应，以及方法描述等内容先开发完毕，就可以提供给前端让他们参照开发了。
2.4 [404]问题解决
正常情况我们按照上面的步骤就可以出现页面，但是有些时候可能是由于springBoot的版本过高导致的，我们输入之前的地址，出现404的情况，这个主要是由于项目中无法读取到swagger依赖包下的页面导致的。如果出现了这个问题，我们可以添加一个配置类，让他实现WebMvcConfigurer 接口，在添加一个方法：
@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/");
}完整代码如下：
package com.lsqingfeng.springboot.config;
import com.lsqingfeng.springboot.interceptor.TokenInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* @className: WebMvcConfig
* @description:webMvc配置
* @author: sh.Liu
* @date: 2022-01-13 09:51
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@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/");
}
}这个时候在启动就可以了！
2.5 替换UI
上面的整个过程已经完成了，但是生成的接口文档的页面，其实很多人不太喜欢，觉得不太符合国人的使用习惯，所有又有一些大神，提供了其他的UI测试页面。这个页面的使用还是比较广泛的。
修改方式：只需引入一个依赖包：
com.github.xiaoymin swagger-bootstrap-ui 1.9.6
然后把刚才实现的那个的那个方法再添加一条：
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");完成代码：
package com.lsqingfeng.springboot.config;
import com.lsqingfeng.springboot.interceptor.TokenInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* @className: WebMvcConfig
* @description:webMvc配置
* @author: sh.Liu
* @date: 2022-01-13 09:51
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
// @Override
// public void addInterceptors(InterceptorRegistry registry) {
// //拦截
// registry.addInterceptor(new TokenInterceptor())
// .addPathPatterns("/**")
// .excludePathPatterns("/login");
// }
@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/");
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
}
}重新启动项目： 访问路径发生了变化：** ip:端口号/doc.html**
页面出现了。我们在看看我们的用户接口：
这个风格确实更加的直观，同时也是可以直接进行调试的。大部分的swagger都用的这个风格的文档。
三. SpringBoot集成swagger3
上面已经很详细的讲解了swagger2的集成方式，而swagger3的集成方式更加的简洁一些。
首先引入依赖：
io.springfox springfox-boot-starter 3.0.0
然后是替换注解： swagger2使用的开启注解是： @EnableSwagger2
而在swagger3中，这个注解要换成： @EnableOpenApi
配置类：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30) // v2 不同
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.swaggerv3.controller")) // 设置扫描路径
.build();
}
}要注意，里边的版本类型换成了 OAS_30, 就是swagger3的意思。
OAS 是 OpenAPI Specification 的简称，翻译成中文就是 OpenAPI 说明书。
同时访问地址：原始地址，也就是没换UI的地址： localhost:8080/swagger-ui/index.html这个要和swagger2区分开。
swagger3的原始UI风格也发生了一些变化：
同时swagger3也是可以更换UI的。方法和swagger2一样。
四. swaggerUI 拦截器和跨域冲突处理
如果我们的项目中有关于跨域的处理，同时还有拦截器，然后还要使用swagger，这种情况大家要注意了，有可能我们的拦截器会将swagger中的页面路径拦截掉导致swagger页面出不来，当我们在拦截器中把swagger的页面排除掉的时候，也有可能会导致跨域配置的失效。
具体解决方案简单提一下：
拦截器：
/**
* 拦截器配置
*
* @author liuShuai
*/
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
@Bean
public TokenInterceptor tokenInterceptor() {
return new TokenInterceptor();
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry
.addInterceptor(tokenInterceptor())
.addPathPatterns("/**")
.excludePathPatterns("/user/login")
.excludePathPatterns("/user/downloadExcel")
.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}跨域配置：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;
/**
* @className: CorsConfig
* @description:
* @author: sh.Liu
* @date: 2020-12-02 10:16
*/
@Configuration
public class CorsConfig {
@Bean
public CorsFilter corsFilter() {
CorsConfiguration config = new CorsConfiguration();
config.addAllowedOrigin("*");
config.setAllowCredentials(true);
config.addAllowedMethod("*");
config.addAllowedHeader("*");
UrlBasedCorsConfigurationSource configSource = new UrlBasedCorsConfigurationSource();
configSource.registerCorsConfiguration("/**", config);
return new CorsFilter(configSource);
}
}用这两种方式去配置，就可以让他们和平共处了。
另： 配套项目代码已托管中gitCode: gitcode.net/lsqingfeng/…
分支： feautre/MybatisPlus
WPS Office是一款面向macOS用户的综合办公套件，将文字处理、电子表格、演示文稿、PDF工具、模板与云协作整合在同一应用中。它兼容常见Microsoft Office格式，支持Intel及Apple芯片Mac，基础功能可免费使用，
Shapr3D是一款面向工业设计、机械工程、建筑概念和三维打印工作流的CAD软件。Mac版采用Parasolid建模内核，支持草图约束、实体建模、工程图、可视化渲染及常见CAD格式交换，并可通过账户在多台设备之间同步项目。
REAPER是Cockos开发的数字音频工作站，提供多轨音频与MIDI录制、剪辑、处理、混音和母带制作工具。Mac版兼容Intel与Apple芯片，支持AU、VST、VST3、CLAP等插件格式，并提供高度可定制的工作流程。
Ableton Live 是面向音乐制作人与现场表演者的数字音频工作站，提供编曲视图、独具特色的现场视图、音频录制、MIDI创作、实时变速、乐器及效果器。Mac版原生支持Apple芯片，并可连接音频接口、MIDI控制器和第三方插件。
Adobe After Effects 是面向动态图形、影视特效与视频合成的专业创作软件。它提供关键帧动画、遮罩抠像、运动跟踪、三维空间、文字动画和表达式等工具，并可与 Premiere Pro、Photoshop、Illustrator
Adobe Audition 是面向播客、影视后期、音乐制作及内容创作者的专业音频工作站，提供波形精修、多轨录制与混音、频谱编辑、降噪修复、响度匹配和效果处理工具，并可与 Adobe Premiere 协同完成视频声音制作。
Adobe Bridge 是面向摄影师、设计师及内容团队的免费数字资产管理工具，可集中预览照片、视频和 Adobe 项目文件，并利用评级、标签、关键词、元数据、筛选与收藏集完成分类检索。它还支持批量重命名、格式导出、相机导入及 Camera
Adobe Illustrator 是 Adobe 推出的专业矢量图形设计软件，适合在 Mac 上制作标志、图标、插画、包装、信息图及印刷版面。它以路径和锚点构建可无损缩放的图形，并提供钢笔、形状、文字、图像描摹、渐变、画板及生成式功能。
Adobe InDesign 是面向印刷品与数字出版物的专业版面设计软件，可在 Mac 上制作书籍、杂志、宣传册、海报、报告及交互式文档。它提供精细的文字样式、网格、母版、长文档管理和印前输出能力。
Adobe Lightroom Classic 是面向桌面摄影工作流的照片管理与后期处理软件，可将原始照片保存在本地硬盘，通过目录、关键词、评分和收藏夹高效整理图库，并提供 RAW 冲印、蒙版、镜头校正、批量同步及多格式导出等功能。
Adobe Media Encoder 是 Adobe 推出的专业音视频编码与转码工具，可通过队列、预设和监视文件夹批量完成格式转换、代理文件创建及多平台成片输出，并与 Premiere Pro、After Effects 等软件紧密协作。
Adobe Photoshop 是面向摄影师、设计师和内容创作者的专业图像处理软件，提供图层、蒙版、选区、修复、调色、文字排版、智能对象及生成式编辑等能力。Mac 版支持 Intel 与 Apple Silicon 处理器。
AutoCAD 是 Autodesk 推出的专业计算机辅助设计软件，Windows 版支持精确二维绘图、三维实体与曲面建模、图纸标注、布局发布和任务自动化，并包含多套行业专业化工具组合，适用于建筑、机械、电气、工程建设及制造设计人员。
SketchUp Pro 是面向建筑、室内、景观、施工和产品设计等专业场景的三维建模工具，提供桌面建模、LayOut 二维文档、模型资源库、扩展程序及云端协作能力。其操作逻辑直观，适合从概念推敲、空间规划到图纸表达和方案汇报的完整工作流程。
AutoCAD LT 是 Autodesk 推出的专业二维 CAD 软件，适合建筑师、工程师、施工人员和设计师完成精确绘图、标注及文档编制。它支持 DWG 工作流、智能块、图形比较、计数、表格和 AutoLISP 自动化，
Rhino 3D 是 McNeel 推出的专业三维建模工具，可创建、编辑和分析 NURBS 曲线曲面、实体、网格、SubD 与点云。Windows 版支持精确造型、工程制图、渲染、文件转换及 Grasshopper 参数化设计，
Autodesk Fusion 是面向产品设计与制造的云连接开发平台，在统一环境中整合三维 CAD、CAM、CAE、PCB、工程图、数据管理和团队协作功能，适合产品设计师、机械工程师、电子工程师及加工制造团队完成从概念建模、验证分析到生产交
Archicad 是 Graphisoft 面向建筑师、设计师、工程师及 BIM 团队开发的建筑信息模型平台。它把三维建筑建模、施工文档、数据管理、专业协调、实时协作和可视化集中在统一项目环境中，适合从概念方案到施工交付的完整建筑设计流程。
Vectorworks Architect 是面向建筑师、室内设计师和建筑顾问的综合设计与BIM平台，覆盖概念草图、二维制图、三维建模、施工文档、数据报表、可视化及开放式协作。它强调自由造型与数据化建筑对象并存，
Shapr3D 是一款基于 Siemens Parasolid 几何内核的专业三维CAD软件，可在 Windows 电脑和平板设备上完成草图绘制、实体建模、参数化修改、模型可视化及技术图纸制作。软件提供免费基础方案，
FreeCAD 是面向机械设计、产品开发、建筑建模和创客项目的免费开源参数化三维 CAD 工具。它可在 Windows 上完成约束草图、实体零件、装配、工程图、BIM、有限元分析及 CAM 等任务，
Twinmotion 是 Epic Games 推出的实时三维可视化工具，可导入常见 CAD、BIM 与三维模型，通过材质、环境、植被、灯光及动画资源快速构建场景，并输出图片、视频、全景图和交互演示。
BricsCAD 是以 DWG 为核心格式的专业 CAD 平台，可用于二维制图、三维建模、工程文档与设计协作。产品按 Lite、Pro、BIM、Mechanical 和 Ultimate 等层级提供不同工具，
Ableton Live 是面向音乐创作、录音、编曲、声音设计、混音与现场演出的数字音频工作站。它将适合即兴触发素材的 Session 视图与传统时间线编曲结合，并提供音频变速、MIDI工具、软件乐器、效果器和声音资源，