Swagger - SpringBoot整合Swagger最佳实践

总结

Swagger UI部分有两种，一种是官方提供的名为swagger-ui，访问路径为/swagger-ui.html，一种是萧明同学提供的swagger-bootstrap-ui，访问路径为/doc.html。后者界面美观，体验较好（GITHUB传送门，体验传送门）。

Swagger的启用和禁用可以通过@ConditionalOnProperty和@Profile({"dev", "test"})来做，但这两种均不推荐，这两种方式在禁用的情况下，swagger-ui会出现死循环弹窗，这在github上的springfox已经有人提出了issue。在swagger-bootstrap-ui会出现请确保swagger资源接口正确。即使不提示，也会出现一个完整的页面，只不过没有接口数据，我们更希望在禁用后访问该路径后自动跳转至我们指定的一个错误页面或者其它页面。推荐使用文中提到的拦截器方式来实现。

最佳实践

一、引入jar包

<!-- Swagger -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency><!-- Swagger 官方UI jar包 -->
<!--<dependency>--><!--<groupId>io.springfox</groupId>--><!--<artifactId>springfox-swagger-ui</artifactId>--><!--<version>2.9.2</version>-->
<!--</dependency>--><!-- 萧明同学提供的 jar 包 -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.3</version>
</dependency>

二、增加配置类，如下

package com.lazymkcg.bml.config;import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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;/*** Swagger配置* @author Caesar Liu* @date 2019/4/24 16:51*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Value("${swagger.host}")private String host;@Value("${swagger.title}")private String title;@Value("${swagger.description}")private String description;@Value("${project.version}")private String version;@Beanpublic ApiInfo getApiInfo() {return new ApiInfoBuilder().title(title).description(description).version(version).build();}@Beanpublic Docket getDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.getApiInfo()).host(host).select()// 设置需要被扫描的类，这里设置为添加了@Api注解的类.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any()).build();}}

三、增加拦截器，用于禁用swagger时进行跳转，如下：

package com.lazymkcg.bml.config;import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;/*** Swagger 拦截器* @description 用于禁用swagger，当swagger.disabled为true时重定向至${swagger.redirect-uri}* @author Caesar Liu* @date 2019/4/24 18:23*/
@Slf4j
@Component
public class SwaggerInterceptor implements HandlerInterceptor {@Value("${swagger.disabled}")private Boolean disabledSwagger;@Value("${swagger.redirect-uri}")private String redirectUri;@Overridepublic boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {if(!disabledSwagger) return Boolean.TRUE;String uri = redirectUri;if(uri == null || uri.trim().length() == 0)uri = "/";try {response.sendRedirect(uri);} catch (IOException e) {log.error(String.format("Redirect to '%s' for swagger throw an exception : %s", uri, e.getMessage()), e);}return Boolean.FALSE;}
}

四、为Swagger拦截器配置拦截路径，拦截/doc.html和/swagger-ui.html

package com.lazymkcg.bml.config;import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;/*** Swagger拦截器配置* @author Caesar Liu* @date 2019/4/24 18:25*/
@Configuration
public class SwaggerInterceptorConfig implements WebMvcConfigurer {@Autowiredprivate SwaggerInterceptor swaggerInterceptor;@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(swaggerInterceptor).addPathPatterns("/swagger-ui.html", "/doc.html");}
}

五、增加项目配置内容（application.yml）如下

# Swagger
swagger:host:title: SpringBoot 整合 Swagger2description: 网站描述disabled: true # 是否禁用swaggerredirect-uri: / # 禁用swagger时的重定向地址

这样，就完成了Swagger的整合和最佳实践。我们可以通过配置文件来配置Swagger的相关信息。

（完）

Swagger - SpringBoot整合Swagger最佳实践相关推荐

六、springboot整合swagger
六.springboot整合swagger 简介 swagger 提供最强大,最易用的工具,以充分利用OpenAPI规范. 官网 : https://swagger.io/ 准备工作 pom.xml ...
Springboot整合swagger指南
Springboot整合swagger指南 1. 安装使用 1.1 下载依赖 <dependency><groupId>io.springfox</groupId> ...
解决高版本SpringBoot整合swagger时启动报错：Failed to start bean ‘documentationPluginsBootstrapper‘ 问题
一.控制台的报错信息 2021-12-29 15:15:04 [main] ERROR org.springframework.boot.SpringApplication - Application ...
springboot整合swagger（高版本）异常
springboot整合swagger(高版本)异常参考文章: (1)springboot整合swagger(高版本)异常 (2)https://www.cnblogs.com/chbyiming- ...
高版本springboot整合swagger
高版本springboot整合swagger 这是我的springboot版本2.6: ![!\[Alt\](https://imgconvert.csdnimg.cn/aHR0cHM6Ly9hdmF ...
springboot整合swagger+knife4j
springboot整合swagger+knife4j 参考网址: https://mp.weixin.qq.com/s/KlYj5JuJSJYQQ47mQu7b1w swagger配置参考文档 sw ...
springboot整合swagger+mybatisplus案例
1.前后端分离的一个常用的文档接口swaggerui越来越受欢迎,方便了前端以及后端人员的测试 2.如下为springboot整合swagger和mybatispus案例的github地址:https ...
Springboot整合Swagger实战（一）
Springboot整合Swagger实战(一) 记录一下自己在开发过程中,遇到的问题及安装环境的步骤(最讨厌安装环境了),希望可以帮到大家. 我在遇到问题的时候也是查找了好多文章,奈何呀,全是问题, ...
SpringBoot整合Swagger测试api构建
@Author:SimpleWu 什么是Swagger? Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspec ...

Swagger - SpringBoot整合Swagger最佳实践

总结

最佳实践

一、引入jar包

二、增加配置类，如下

三、增加拦截器，用于禁用swagger时进行跳转，如下：

四、为Swagger拦截器配置拦截路径，拦截/doc.html和/swagger-ui.html

五、增加项目配置内容（application.yml）如下

Swagger - SpringBoot整合Swagger最佳实践相关推荐

最新文章

热门文章