文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

Swagger3的优点有哪些

2024-04-02 19:55

关注

这篇文章主要介绍“Swagger3的优点有哪些”,在日常操作中,相信很多人在Swagger3的优点有哪些问题上存在疑惑,小编查阅了各式资料,整理出简单好用的操作方法,希望对大家解答”Swagger3的优点有哪些”的疑惑有所帮助!接下来,请跟着小编一起来学习吧!

Swagger3集成

Swagger目前最新版本是3.0.0,在Spring  Boot应用中集成Swagger3比老的Swagger2简单多了,它提供了一个Starter组件。

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

就这就可以了,简单不?

至于有的教程说还要开启注解@EnableOpenApi,完全不需要。因为在springfox-boot-starter-3.0.0.jar下你可以找到一个spring.factories,熟悉Spring  Boot的同学都知道这个是一个Spring Boot 特有的SPI文件,能够自动的发现并注册Starter组件的配置。里面有这样的配置:

# Auto Configure org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration

顺藤摸瓜,找到总的配置类OpenApiAutoConfiguration:

@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注解声明了当springfox.documentation.enabled为true时启用配置,而且默认值就是true。这非常有用,Swagger仅仅建议在开发阶段使用,这个正好是个开关。另外有时候我们自定义配置的时候最好把这个开关也加上:

// 自定义swagger3文档信息 @Configuration @ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true) public class Swagger3Config {     @Bean     public Docket createRestApi() {         return new Docket(DocumentationType.OAS_30)                 .apiInfo(apiInfo())                 .select()                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                 .paths(PathSelectors.any())                 .build();     }      private ApiInfo apiInfo() {         return new ApiInfoBuilder()                 .title("Swagger3接口文档")                 .description("更多请咨询felord.cn")                 .contact(new Contact("码农小胖哥", "https://felord.cn", "dax@felord.cn"))                 .version("1.0.0")                 .build();     } }

如果你想在Swagger3中加入Json Web Token,可以参考这篇文章。

最开始我们提到Swagger3不需要使用@EnableOpenApi或者@EnableSwagger2开启,这里也能找到答案。

@Import(OpenApiDocumentationConfiguration.class) public @interface EnableOpenApi { } @Import(Swagger2DocumentationConfiguration.class) public @interface EnableSwagger2 { }

上面的两个导入类都可以在OpenApiAutoConfiguration找到,所以Swagger3提供的是全自动的集成。

和全局统一参数不兼容

如果你使用了统一返回体封装器来标准化Spring MVC接口的统一返回

 @RestControllerAdvice  public class RestBodyAdvice implements ResponseBodyAdvice<Object> {     @Override     public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {         return !returnType.hasMethodAnnotation(IgnoreRestBody.class);     }      @Override     public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {          if (body == null) {             return RestBody.ok();         }         if (Rest.class.isAssignableFrom(body.getClass())) {             return body;         }         return RestBody.okData(body);     } }

你会发现Swagger3会报Unable to infer base  url&hellip;&hellip;的错误,这是因为统一返回体影响到了Swagger3的一些内置接口。解决方法是@RestControllerAdvice控制好生效的包范围,也就是配置其basePackages参数就行了,这个潜在的冲突浪费我了一个多小时。

安全框架放行

如果你使用安全框架,Swagger3的内置接口就会访问受限,我们需要排除掉。Spring Security是这么配置的:

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

如果你使用的版本是Spring Security 5.4,你可以这么定制WebSecurity:

@Bean WebSecurityCustomizer swaggerWebSecurityCustomizer() {     return (web) -> {         web.ignoring().antMatchers(new String[]{"/swagger-ui.html", "/swagger-ui/**", "/swagger-resources/**", "/v2/api-docs", "/v3/api-docs", "/webjars/**"});     }; }

更加方便简单图片,这样Swagger就能正常的渲染和访问了。

到此,关于“Swagger3的优点有哪些”的学习就结束了,希望能够解决大家的疑惑。理论与实践的搭配能更好的帮助大家学习,快去试试吧!若想继续学习更多相关知识,请继续关注编程网网站,小编会继续努力为大家带来更多实用的文章!

阅读原文内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-前端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯