Swagger3的优点有哪些
这篇文章主要介绍“Swagger3的优点有哪些”,在日常操作中,相信很多人在Swagger3的优点有哪些问题上存在疑惑,小编查阅了各式资料,整理出简单好用的操作方法,希望对大家解答”Swagger3的优点有哪些”的疑惑有所帮助!接下来,请跟着小编一起来学习吧!
创新互联服务项目包括西岗网站建设、西岗网站制作、西岗网页制作以及西岗网络营销策划等。多年来,我们专注于互联网行业,利用自身积累的技术优势、行业经验、深度合作伙伴关系等,向广大中小型企业、政府机构等提供互联网行业的解决方案,西岗网站推广取得了明显的社会效益与经济效益。目前,我们服务的客户以成都为中心已经辐射到西岗省份的部分城市,未来相信会继续扩大服务区域并继续获得客户的支持与信任!
Swagger3集成
Swagger目前最新版本是3.0.0,在Spring Boot应用中集成Swagger3比老的Swagger2简单多了,它提供了一个Starter组件。
io.springfox springfox-boot-starter 3.0.0
就这就可以了,简单不?
至于有的教程说还要开启注解@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接口的统一返回
/** * 返回体统一封装器 * * @author n1 */ @RestControllerAdvice public class RestBodyAdvice implements ResponseBodyAdvice
你会发现Swagger3会报Unable to infer base url……的错误,这是因为统一返回体影响到了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的优点有哪些”的学习就结束了,希望能够解决大家的疑惑。理论与实践的搭配能更好的帮助大家学习,快去试试吧!若想继续学习更多相关知识,请继续关注创新互联网站,小编会继续努力为大家带来更多实用的文章!
分享名称:Swagger3的优点有哪些
分享URL:http://ybzwz.com/article/ppggcs.html