优雅的配置(升级)swagger3

Swagger目前最新版本是3.0.0,在Spring Boot应用中集成Swagger3比老的Swagger2简单的多。

以下讲解 适用于swagger2升级swagger3，及新版本直接采用swagger3的项目~。

作者现有的项目采用的是swagger2，升级swagger3的时候顺便学习了下。

swagger3配置项

1.依赖项

3的依赖相比2略有不同，不过都是springfox家的，由于springfox家的swagger3兼容swagger2的注解，所以这里升级使用的是springfox实现的swagger3！还有一个springdoc实现的是不兼容的！注意。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.swagger配置类

@Configuration
//@EnableSwagger2 //swagger3版本不需要使用这个注解，当然写上也无所谓~
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)  // swagger2版本这里是DocumentationType.SWAGGER_2
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx管理平台")
                .description("xxx管理平台 API接口文档")
                .license("xxx有限公司")
                .licenseUrl("xxx")
                .version("1.0")
                .build();
    }
}

这里要修改一处，就是把DocumentationType.SWAGGER_2修改为DocumentationType.OAS_30。

至于有的教程说还要开启注解@EnableOpenApi，或者@EnableSwagger2，完全不需要。

这里要提到一位作者，比较详细的讲了为啥不需要写注解的原因，详情不在多做描述：传送门 感谢~。这篇文章讲到swagger3是全自动的集成，所以配置项会少的可怜。

3.在生产版本禁用swagger3

在swagger3的源码里有这样一段代码：

@Configuration
@EnableConfigurationProperties(SpringfoxConfigurationProperties.class)
@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)
@Import({
    OpenApiDocumentationConfiguration.class,
    SpringDataRestConfiguration.class,
    BeanValidatorPluginsConfiguration.class,
    Swagger2DocumentationConfiguration.class,
    SwaggerUiWebFluxConfiguration.class,
    SwaggerUiWebMvcConfiguration.class
})
@AutoConfigureAfter({ WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class,
    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class })
public class OpenApiAutoConfiguration {

}

我们找到了关键的一个地方

@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)

@ConditionalOnProperty注解声明了当springfox.documentation.enabled为true时启用配置，而且默认值就是true。这非常有用，Swagger仅仅建议在开发阶段使用，这个正好是个开关。另外我们自定义配置的时候最好把这个开关也加上，通过在配置文件中写上springfox.documentation.enabled=false来在生成版本中禁用swagger3！

springfox.documentation.enabled=false

4.路径放行

如果使用了拦截器或者spring security则需要放行一些swagger必要的路径。

@Override
    public void configure(WebSecurity web) {
        //忽略swagger3所需要用到的静态资源，允许访问
        String[] swaggerUrl = new String[]{
                "/swagger-ui/**",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**",                
        };
        web.ignoring().antMatchers(swaggerUrl);
    }

到这里就可以成功访问swaggerUI了。

注意：swagger3和swagger2访问路径不同，swagger2：/swagger-ui.html ，swagger3: /swagger-ui/

如图

 美化swagger

swagger3配置成功了，显然它的界面和swagger2差别并不大，接下来，学习，美化swaggerUI界面。

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。

1.下载依赖项

        <dependency>
            <groupId>com.github.shijingsh</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.5</version>
        </dependency>

这里要移除掉swagger3的依赖，因为knife4j已经集成swagger3了，为了防止产生不必要的错误。

2.路径放行

String[] swaggerUrl = new String[]{
                "/swagger-ui/**",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**",
                "/doc.html",  // 在原有的swagger3放行基础上加上 /doc.html
        };

3.在生产版本禁用swagger3

knife4j:
  # 开启增强配置
  enable: true
  # 开启生产环境屏蔽
  production: true

swagger配置类不用修改，直接访问页面：/doc.html

这里贴一下官方的图，vue风格的ui界面就出来了！

更多的配置项可以查看官方文档：传送门