阿里 做网站,北京市住房建设网站,农家乐网站源码,苏州网上注册公司网址SpringBoot教程(十六) | SpringBoot集成swagger#xff08;全网最全#xff09; 一. 接口文档概述 swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具#xff0c;在前后端开发之前#xff0c;后端要先出接口文档#xff0c…SpringBoot教程(十六) | SpringBoot集成swagger全网最全 一. 接口文档概述 swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具在前后端开发之前后端要先出接口文档前端根据接口文档来进行项目的开发双方开发结束后在进行联调测试。 所以接口文档其实就是开发之前双方之间的一种约定。通常接口文档分为离线的和实时的。离线的接口文档工具有 word(相当于没说) YAPI, 小幺鸡等这种文档需要程序员在上面编写也一般具备接口测试功能。通常是由开发人员先在离线接口文档上编写信息然后交给前端人员参照开发。最大的弊端是当我们的接口程序发生变动时需要回过头来维护上面的内容很麻烦是真的麻烦。 实时接口文档就是可以根据我们的代码来自动生成相应的接口文档优点就是我们的代码发生变化时生成的接口文档也会自动更新无需我们关注修改主需要按时发布即可。但是由于是根据代码自动生成的所以最大的弊端就是代码侵入性强需要我们在项目代码中集成生成接口文档的相关代码。实时接口文档现在的方案有很多但是swagger还是其中比较有影响力的一个。 二. SpringBoot集成swagger2 官网地址 swagger.io 当然官网都是英文的看起来还是比较麻烦的。建议大家直接按照我的步骤来还是很简单的。 同时在说一点 swagger分为swagger2 和swagger3两个常用版本。二者区别不是很大主要对于依赖和注解进行了优化。swagger2需要引入2个jar包swagger3只需要一个用起来没有什么大的区别。下面以swagger2为例。 2.1 引入依赖 xml复制代码dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version /dependency dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version /dependency2.2 引入配置 首先需要添加一个注解 EnableSwagger2。 这个注解我们可以添加到SpringBoot的启动类上也可以自定义一个配置类放到上面。添加了这个注解以后就代表我们已经在项目中开启了Swagger的功能。 我们采用第二种方式自己定义一个配置类正好还可以添加一个Docket配置。 所谓Docket配置就是一组(一个项目或一个版本)接口文档的配置比如设置名称 联系人等等。 我们在config文件夹下添加一个SwaggerConfig类。 java复制代码Configuration EnableSwagger2 public class SwaggerConfig {/*** 设置多个** Bean* public Docket appApi() {** ListParameter 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() {** ListParameter 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*/Beanpublic 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.Listspringfox.documentation.service.Parameter*/private ListParameter setHeaderToken() {ListParameter 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定义出请求和响应的数据结构。注意这里要添加相应的注解 请求类 java复制代码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; }响应类 java复制代码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: java复制代码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配置文件中添加配置 properties 复制代码spring.mvc.pathmatch.matching-strategyANT_PATH_MATCHER如果是yml格式的配置文件 再次启动问题解决。 访问地址 ip:端口号/swagger-ui.html 正常情况就可以看到我们的界面了。一会再说非正常情况。由于我们只给用户接口添加了注解所有用户接口是可以直接观察中文文档的。而剩下的两个接口由于没添加注解所以都是以默认的形式展示的。 点开接口我们可以看到接口中的想详细信息 点击model,可以看到字段的中文描述。点击 Try it out,就可以直接调试接口。同时注意接口中都让填一个token,这就是我们之前的设置成效了。 截止到目前其实swagger的集成就已经完毕了主要就是根据我们的注解生成文档并且可以在线调用调试。开发的时候我们只需要把Controller这一层的请求和响应以及方法描述等内容先开发完毕就可以提供给前端让他们参照开发了。 2.4 [404]问题解决 正常情况我们按照上面的步骤就可以出现页面但是有些时候可能是由于springBoot的版本过高导致的我们输入之前的地址出现404的情况这个主要是由于项目中无法读取到swagger依赖包下的页面导致的。如果出现了这个问题我们可以添加一个配置类让他实现WebMvcConfigurer 接口在添加一个方法 java复制代码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/); }完整代码如下 java复制代码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 {Overridepublic 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测试页面。这个页面的使用还是比较广泛的。 修改方式只需引入一个依赖包 xml复制代码dependencygroupIdcom.github.xiaoymin/groupIdartifactIdswagger-bootstrap-ui/artifactIdversion1.9.6/version /dependency然后把刚才实现的那个的那个方法再添加一条 java复制代码registry.addResourceHandler(doc.html).addResourceLocations(classpath:/META-INF/resources/);完成代码 java复制代码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); // }Overridepublic 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的集成方式更加的简洁一些。 首先引入依赖 xml复制代码dependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version /dependency然后是替换注解 swagger2使用的开启注解是 EnableSwagger2 而在swagger3中这个注解要换成 EnableOpenApi 配置类 java复制代码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 {Beanpublic 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的页面排除掉的时候也有可能会导致跨域配置的失效。 详细的解决方案可以看我之前写过的一篇博客 lsqingfeng.blog.csdn.net/article/det… 具体解决方案简单提一下 拦截器 java复制代码/*** 拦截器配置** author liuShuai*/ Configuration public class InterceptorConfig implements WebMvcConfigurer {Beanpublic TokenInterceptor tokenInterceptor() {return new TokenInterceptor();}Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(tokenInterceptor()).addPathPatterns(/**).excludePathPatterns(/user/login).excludePathPatterns(/user/downloadExcel).excludePathPatterns(/swagger-resources/**, /webjars/**, /v2/**, /swagger-ui.html/**);}Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler(swagger-ui.html).addResourceLocations(classpath:/META-INF/resources/);registry.addResourceHandler(/webjars/**).addResourceLocations(classpath:/META-INF/resources/webjars/);} }跨域配置 java复制代码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 {Beanpublic 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 所有文章也会在微信公众号首发更新欢迎关注 一缕82年的清风 五. 写在最后 截止到本篇文章关于SpringBoot的系列学习笔记已经更新了十六篇也基本上要和大家说再见了。感谢大家的一路支持。这十六篇文章主要面向SpringBoot的实战性学习上基本很少会介绍一些原理性的概念。也已经集成目前大部分主流的框架和中间件。如果大家对于Spring中一些生命周期初始化过程类加载原理和常用注解不太了解因为这一个部分很少介绍建议大家结合我之前写的Spring5系列教程一起学习里边介绍了Spring IOC和AOP的核心概念。 这个系列的教程就更新到这里了后面可能就不会在继续更新这个系列了。下个目标我可能准备写一个SpringCloud的系列教程主要针对alibaba版本中的一些组件用法。但是由于最近公司比较忙可能更新的会比较慢。希望大家多多支持。 心怀感恩不说再见咱们下个系列见