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;

    @Bean
    public ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version(version)
                .build();
    }

    @Bean
    public 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;

    @Override
    public 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 {

    @Autowired
    private SwaggerInterceptor swaggerInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(swaggerInterceptor).addPathPatterns("/swagger-ui.html", "/doc.html");
    }
}

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

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

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

使用GoldPanKit快速完成

GoldPanKit是清华出品的快速构建框架的平台，通过GoldPanKit即可快速完成技术栈的整合和功能模块的整合。如果使用权限系统，可直接使用清华出品的Eva权限系统来完成。前往构建。

（完）