小鸭子的学习笔记duck

Duck Blog

唐如飞

( ^∀^)/欢迎\( ^∀^)

79 文章数
14 评论数

优雅的配置(升级)swagger3

tangrufei
2023-03-29 / 0 评论 / 249 阅读 / 0 点赞

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

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

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

swagger3配置项

依赖项

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界面就出来了!

————————————————
版权声明:本文为CSDN博主「ds_surk」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
原文链接:https://blog.csdn.net/hunt_er/article/details/122981544

文章不错,扫码支持一下吧~
上一篇 下一篇
评论
来首音乐
光阴似箭
今日已经过去小时
这周已经过去
本月已经过去
今年已经过去个月