1 依赖引入

  1. <parent>
  2.   <groupId>org.springframework.boot</groupId>
  3.   <artifactId>spring-boot-starter-parent</artifactId>
  4.   <version>2.1.4.RELEASE</version>
  5. </parent>
  6. <dependencies>
  7.   <dependency>
  8.     <groupId>io.springfox</groupId>
  9.     <artifactId>springfox-boot-starter</artifactId>
  10.     <version>3.0.0</version>
  11.   </dependency>
  12.   <!--fastjson-->
  13.   <dependency>
  14.     <groupId>com.alibaba</groupId>
  15.     <artifactId>fastjson</artifactId>
  16.     <version>1.2.51</version>
  17.   </dependency>
  19.   <!--测试包-->
  20.   <dependency>
  21.     <groupId>org.springframework.boot</groupId>
  22.     <artifactId>spring-boot-starter-test</artifactId>
  23.   </dependency>
  24.   <dependency>
  25.     <groupId>org.springframework.boot</groupId>
  26.     <artifactId>spring-boot-starter-web</artifactId>
  27.   </dependency>
  28.   <!-- 文件处理器-->
  29.   <dependency>
  30.     <groupId>org.springframework.boot</groupId>
  31.     <artifactId>spring-boot-configuration-processor</artifactId>
  32.     <optional>true</optional>
  33.   </dependency>
  34.   <dependency>
  35.     <groupId>org.apache.commons</groupId>
  36.     <artifactId>commons-lang3</artifactId>
  37.     <version>3.8</version>
  38.   </dependency>
  39.   <!-- Work around springfox -->
  40.   <!-- https://mvnrepository.com/artifact/org.springframework.plugin/spring-plugin-core -->
  41.   <dependency>
  42.     <groupId>org.springframework.plugin</groupId>
  43.     <artifactId>spring-plugin-core</artifactId>
  44.     <version>2.0.0.RELEASE</version>
  45.   </dependency>
  48. </dependencies>

2 application.yml

  1. spring:
  2.   application:
  3.     name: springfox-swagger
  4. server:
  5.   port: 8080
  7. # ===== 自定义swagger配置 ===== #
  8. swagger:
  9.   enable: true
  10.   application-name: ${spring.application.name}
  11.   application-version: 1.0
  12.   application-description: springfox swagger 3.0整合Demo
  13.   try-host: http://localhost:${server.port}

3 启动类

  1. @SpringBootApplication
  2. @EnableOpenApi
  3. public class Swagger3Application {
  5.     public static void main(String[] args){
  6.         SpringApplication.run(Swagger3Application.class,args);
  7.     }
  8. }

4 读取文件配置

  1. package com.hikktn.vo;
  3. import org.springframework.boot.context.properties.ConfigurationProperties;
  4. import org.springframework.stereotype.Component;
  6. /**
  7.  * @author hikktn
  8.  */
  9. @Component
  10. @ConfigurationProperties("swagger")
  11. public class SwaggerProperties {
  12.     /**
  13.      * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
  14.      */
  15.     private Boolean enable;
  17.     /**
  18.      * 项目应用名
  19.      */
  20.     private String applicationName;
  22.     /**
  23.      * 项目版本信息
  24.      */
  25.     private String applicationVersion;
  27.     /**
  28.      * 项目描述信息
  29.      */
  30.     private String applicationDescription;
  32.     /**
  33.      * 接口调试地址
  34.      */
  35.     private String tryHost;
  37.     public Boolean getEnable() {
  38.         return enable;
  39.     }
  41.     public void setEnable(Boolean enable) {
  42.         this.enable = enable;
  43.     }
  45.     public String getApplicationName() {
  46.         return applicationName;
  47.     }
  49.     public void setApplicationName(String applicationName) {
  50.         this.applicationName = applicationName;
  51.     }
  53.     public String getApplicationVersion() {
  54.         return applicationVersion;
  55.     }
  57.     public void setApplicationVersion(String applicationVersion) {
  58.         this.applicationVersion = applicationVersion;
  59.     }
  61.     public String getApplicationDescription() {
  62.         return applicationDescription;
  63.     }
  65.     public void setApplicationDescription(String applicationDescription) {
  66.         this.applicationDescription = applicationDescription;
  67.     }
  69.     public String getTryHost() {
  70.         return tryHost;
  71.     }
  73.     public void setTryHost(String tryHost) {
  74.         this.tryHost = tryHost;
  75.     }
  76. }

5 Swagger3配置

  1. package com.hikktn.config;
  3. import com.hikktn.vo.SwaggerProperties;
  4. import io.swagger.annotations.ApiOperation;
  5. import io.swagger.models.auth.In;
  6. import org.apache.commons.lang3.reflect.FieldUtils;
  7. import org.springframework.boot.SpringBootVersion;
  8. import org.springframework.context.annotation.Bean;
  9. import org.springframework.context.annotation.Configuration;
  10. import org.springframework.util.ReflectionUtils;
  11. import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
  12. import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
  13. import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
  14. import springfox.documentation.builders.ApiInfoBuilder;
  15. import springfox.documentation.builders.PathSelectors;
  16. import springfox.documentation.builders.RequestHandlerSelectors;
  17. import springfox.documentation.oas.annotations.EnableOpenApi;
  18. import springfox.documentation.service.*;
  19. import springfox.documentation.spi.DocumentationType;
  20. import springfox.documentation.spi.service.contexts.SecurityContext;
  21. import springfox.documentation.spring.web.plugins.Docket;
  23. import java.lang.reflect.Field;
  24. import java.util.*;
  26. /**
  27.  * @Author hikktn
  28.  * @Description swagger3配置
  29.  */
  30. @EnableOpenApi
  31. @Configuration
  32. public class SwaggerConfiguration implements WebMvcConfigurer {
  33.     private final SwaggerProperties swaggerProperties;
  35.     public SwaggerConfiguration(SwaggerProperties swaggerProperties) {
  36.         this.swaggerProperties = swaggerProperties;
  37.     }
  39.     @Bean
  40.     public Docket createRestApi() {
  41.         return new Docket(DocumentationType.OAS_30).pathMapping("/")
  42.                 // 定义是否开启swagger，false为关闭，可以通过变量控制
  43.                 .enable(swaggerProperties.getEnable())
  44.                 // 将api的元信息设置为包含在json ResourceListing响应中。
  45.                 .apiInfo(apiInfo())
  46.                 // 接口调试地址
  47.                 .host(swaggerProperties.getTryHost())
  48.                 // 选择哪些接口作为swagger的doc发布
  49.                 .select()
  50.                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
  51.                 .paths(PathSelectors.any())
  52.                 .build()
  53.                 // 支持的通讯协议集合
  54.                 .protocols(newHashSet("https", "http"))
  55.                 // 授权信息设置，必要的header token等认证信息
  56.                 .securitySchemes(securitySchemes())
  57.                 // 授权信息全局应用
  58.                 .securityContexts(securityContexts());
  59.     }
  61.     /**
  62.      * API 页面上半部分展示信息
  63.      */
  64.     private ApiInfo apiInfo() {
  65.         return new ApiInfoBuilder().title(swaggerProperties.getApplicationName() + " Api Doc")
  66.                 .description(swaggerProperties.getApplicationDescription())
  67.                 .contact(new Contact("lighter", null, "123456@gmail.com"))
  68.                 .version("Application Version: " + swaggerProperties.getApplicationVersion() + ", Spring Boot Version: " + SpringBootVersion.getVersion())
  69.                 .build();
  70.     }
  72.     /**
  73.      * 设置授权信息
  74.      */
  75.     private List<SecurityScheme> securitySchemes() {
  76.         ApiKey apiKey = new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue());
  77.         return Collections.singletonList(apiKey);
  78.     }
  80.     /**
  81.      * 授权信息全局应用
  82.      */
  83.     private List<SecurityContext> securityContexts() {
  84.         return Collections.singletonList(
  85.                 SecurityContext.builder()
  86.                         .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
  87.                         .build()
  88.         );
  89.     }
  91.     @SafeVarargs
  92.     private final <T> Set<T> newHashSet(T... ts) {
  93.         if (ts.length > 0) {
  94.             return new LinkedHashSet<>(Arrays.asList(ts));
  95.         }
  96.         return null;
  97.     }
  99.     /**
  100.      * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
  101.      */
  102.     @SuppressWarnings("unchecked")
  103.     @Override
  104.     public void addInterceptors(InterceptorRegistry registry) {
  105.         try {
  106.             Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
  107.             List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
  108.             if (registrations != null) {
  109.                 for (InterceptorRegistration interceptorRegistration : registrations) {
  110.                     interceptorRegistration
  111.                             .excludePathPatterns("/swagger**/**")
  112.                             .excludePathPatterns("/webjars/**")
  113.                             .excludePathPatterns("/v3/**")
  114.                             .excludePathPatterns("/doc.html");
  115.                 }
  116.             }
  117.         } catch (Exception e) {
  118.             e.printStackTrace();
  119.         }
  120.     }
  121. }

6 控制器

  1. package com.hikktn.vo;
  3. import org.springframework.boot.context.properties.ConfigurationProperties;
  4. import org.springframework.stereotype.Component;
  6. /**
  7.  * @author hikktn
  8.  */
  9. @Component
  10. @ConfigurationProperties("swagger")
  11. public class SwaggerProperties {
  12.     /**
  13.      * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
  14.      */
  15.     private Boolean enable;
  17.     /**
  18.      * 项目应用名
  19.      */
  20.     private String applicationName;
  22.     /**
  23.      * 项目版本信息
  24.      */
  25.     private String applicationVersion;
  27.     /**
  28.      * 项目描述信息
  29.      */
  30.     private String applicationDescription;
  32.     /**
  33.      * 接口调试地址
  34.      */
  35.     private String tryHost;
  37.     public Boolean getEnable() {
  38.         return enable;
  39.     }
  41.     public void setEnable(Boolean enable) {
  42.         this.enable = enable;
  43.     }
  45.     public String getApplicationName() {
  46.         return applicationName;
  47.     }
  49.     public void setApplicationName(String applicationName) {
  50.         this.applicationName = applicationName;
  51.     }
  53.     public String getApplicationVersion() {
  54.         return applicationVersion;
  55.     }
  57.     public void setApplicationVersion(String applicationVersion) {
  58.         this.applicationVersion = applicationVersion;
  59.     }
  61.     public String getApplicationDescription() {
  62.         return applicationDescription;
  63.     }
  65.     public void setApplicationDescription(String applicationDescription) {
  66.         this.applicationDescription = applicationDescription;
  67.     }
  69.     public String getTryHost() {
  70.         return tryHost;
  71.     }
  73.     public void setTryHost(String tryHost) {
  74.         this.tryHost = tryHost;
  75.     }
  76. }

7 测试

访问url：
http://localhost:8080/swagger-ui/index.html
image.png