当前位置:首页 > 公众号精选 > 架构师社区
[导读]目录前言官方文档如何说?SpringBoot版本说明添加依赖springfox-boot-starter做了什么?撸起袖子就是干?定制一个基本的文档示例文档如何分组?如何添加授权信息?如何携带公共的请求参数?粗略是一个BUG总结前言最近频繁被Swagger3.0刷屏,官方表示这是...

目录

  • 前言
  • 官方文档如何说?
  • Spring Boot版本说明
  • 添加依赖
  • springfox-boot-starter做了什么?
  • 撸起袖子就是干?
    • 定制一个基本的文档示例
    • 文档如何分组?
    • 如何添加授权信息?
    • 如何携带公共的请求参数?
  • 粗略是一个BUG
  • 总结

前言

最近频繁被ge: none;background-position: initial;background-size: initial;background-repeat: initial;background-attachment: initial;background-origin: initial;background-clip: initial;">Swagger 3.0刷屏,官方表示这是一个突破性的变更,有很多的亮点,我还真不太相信,今天来带大家尝尝鲜,看看这碗汤到底鲜不鲜....

官方文档如何说?

该项目开源在Github上,地址:https://github.com/springfox/springfox。

Swagger 3.0有何改动?官方文档总结如下几点:

  1. 删除了对springfox-swagger2的依赖
  2. 删除所有@EnableSwagger2...注解
  3. 添加了springfox-boot-starter依赖项
  4. 移除了guava等第三方依赖
  5. 文档访问地址改变了,改成了http://ip:port/project/swagger-ui/index.html
姑且看到这里,各位初始感觉如何?

Swagger3.0 天天刷屏,真的香吗?
既然人家更新出来了,咱不能不捧场,下面就介绍下Spring Boot如何整合Swagger 3.0吧。

Spring Boot版本说明

作者使用Spring Boot的版本是2.3.5.RELEASE

添加依赖

Swagger 3.0已经有了与Spring Boot整合的启动器,只需要添加以下依赖:

  <dependency>
       <groupId>io.springfoxgroupId>
       <artifactId>springfox-boot-starterartifactId>
       <version>3.0.0version>
  dependency>

springfox-boot-starter做了什么?

Swagger 3.0主推的一大特色就是这个启动器,那么这个启动器做了什么呢?

「记住」:启动器的一切逻辑都在自动配置类中。

找到springfox-boot-starter的自动配置类,在/META-INF/spring.factories文件中,如下:

Swagger3.0 天天刷屏,真的香吗?
从上图可以知道,自动配置类就是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.classJacksonAutoConfiguration.class,
    HttpMessageConvertersAutoConfiguration.classRepositoryRestMvcAutoConfiguration.class })
public class OpenApiAutoConfiguration 
{

}
敢情这个自动配置类啥也没干,就光导入了几个配置类(@Import)以及开启了属性配置(@EnableConfigurationProperties)。

Swagger3.0 天天刷屏,真的香吗?
「重点」:记住OpenApiDocumentationConfiguration这个配置类,初步看来这是个BUG,本人也不想深入,里面的代码写的实在拙劣,注释都不写。

撸起袖子就是干?

说真的,还是和以前一样,真的没什么太大的改变,按照文档的步骤一步步来。

定制一个基本的文档示例

一切的东西还是需要配置类手动配置,说真的,我以为会在全局配置文件中自己配置就行了。哎,想多了。配置类如下:

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(value = {SwaggerProperties.class})
public class SwaggerConfig 
{
  /**
     * 配置属性
     */

    @Autowired
    private SwaggerProperties properties;

    @Bean
    public Docket frontApi() {
        return new Docket(DocumentationType.OAS_30)
                //是否开启,根据环境配置
                .enable(properties.getFront().getEnable())
                .groupName(properties.getFront().getGroupName())
                .apiInfo(frontApiInfo())
                .select()
                //指定扫描的包
                .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 前台API信息
     */

    private ApiInfo frontApiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getFront().getTitle())
                .description(properties.getFront().getDescription())
                .version(properties.getFront().getVersion())
                .contact(    //添加开发者的一些信息
                        new Contact(properties.getFront().getContactName(), properties.getFront().getContactUrl(),
                                properties.getFront().getContactEmail()))
                .build();
    }
}
@EnableOpenApi这个注解文档解释如下:

Indicates that Swagger support should be enabled.
This should be applied to a Spring java config and should have an accompanying '@Configuration' annotation.
Loads all required beans defined in @see SpringSwaggerConfig
什么意思呢?大致意思就是「只有在配置类标注了@EnableOpenApi这个注解才会生成Swagger文档」

@EnableConfigurationProperties这个注解使开启自定义的属性配置,这是作者自定义的Swagger配置。

总之还是和之前一样配置,根据官方文档要求,需要在配置类上加一个@EnableOpenApi注解。

文档如何分组?

我们都知道,一个项目可能分为前台后台APP端小程序端.....每个端的接口可能还相同,不可能全部放在一起吧,肯定是要区分开的。

因此,实际开发中文档肯定是要分组的。

分组其实很简单,SwaggerIOC中注入一个Docket即为一个组的文档,其中有个groupName()方法指定分组的名称。

因此只需要注入多个Docket指定不同的组名即可,当然,这些文档的标题、描述、扫描的路径都是可以不同定制的。

如下配置两个Docket,分为前台和后台,配置类如下:

@EnableOpenApi
@Configuration
@EnableConfigurationProperties(value = {SwaggerProperties.class})
public class SwaggerConfig 
{
  /**
     * 配置属性
     */

    @Autowired
    private SwaggerProperties properties;

    @Bean
    public Docket frontApi() {
        return new Docket(DocumentationType.OAS_30)
                //是否开启,根据环境配置
                .enable(properties.getFront().getEnable())
                .groupName(properties.getFront().getGroupName())
                .apiInfo(frontApiInfo())
                .select()
                //指定扫描的包
                .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 前台API信息
     */

    private ApiInfo frontApiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getFront().getTitle())
                .description(properties.getFront().getDescription())
                .version(properties.getFront().getVersion())
                .contact(    //添加开发者的一些信息
                        new Contact(properties.getFront().getContactName(), properties.getFront().getContactUrl(),
                                properties.getFront().getContactEmail()))
                .build();
    }
    
    /**
     * 后台API
     */

    @Bean
    public Docket backApi() {
        return new Docket(DocumentationType.OAS_30)
                //是否开启,根据环境配置
                .enable(properties.getBack().getEnable())
                .groupName("后台管理")
                .apiInfo(backApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(properties.getBack().getBasePackage()))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 后台API信息
     */

    private ApiInfo backApiInfo() {
        return new ApiInfoBuilder()
                .title(properties.getBack().getTitle())
                .description(properties.getBack().getDescription())
                .version(properties.getBack().getVersion())
                .contact(    //添加开发者的一些信息
                        new Contact(properties.getBack().getContactName(), properties.getBack().getContactUrl(),
                                properties.getBack().getContactEmail()))
                .build();
    }
    
}
属性配置文件SwaggerProperties如下,分为前台和后台两个不同属性的配置:

/**
 * swagger的属性配置类
 */

@ConfigurationProperties(prefix = "spring.swagger")
@Data
public class SwaggerProperties {

    /**
     * 前台接口配置
     */

    private SwaggerEntity front;

    /**
     * 后台接口配置
     */

    private SwaggerEntity back;

    @Data
    public static class SwaggerEntity {
        private String groupName;
        private String basePackage;
        private String title;
        private String description;
        private String contactName;
        private String contactEmail;
        private String contactUrl;
        private String version;
        private Boolean enable;
    }
}
此时的文档截图如下,可以看到有了两个不同的分组:

Swagger3.0 天天刷屏,真的香吗?

如何添加授权信息?

现在项目API肯定都需要权限认证,否则不能访问,比如请求携带一个TOKEN

在Swagger中也是可以配置认证信息,这样在每次请求将会默认携带上。

Docket中有如下两个方法指定授权信息,分别是securitySchemes()securityContexts()。在配置类中的配置如下,在构建Docket的时候设置进去即可:


    @Bean
    public Docket frontApi() {
        RequestParameter parameter = new RequestParameterBuilder()
                .name("platform")
                .description("请求头")
                .in(ParameterType.HEADER)
                .required(true)
                .build();
        List parameters = Collections.singletonList(parameter);
        return new Docket(DocumentationType.OAS_30)
                //是否开启,根据环境配置
                .enable(properties.getFront().getEnable())
                .groupName(properties.getFront().getGroupName())
                .apiInfo(frontApiInfo())
                .select()
                //指定扫描的包
                .apis(RequestHandlerSelectors.basePackage(properties.getFront().getBasePackage()))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    /**
     * 设置授权信息
     */

    private List securitySchemes() {
        ApiKey apiKey = new ApiKey("BASE_TOKEN""token", In.HEADER.toValue());
        return Collections.singletonList(apiKey);
    }

    /**
     * 授权信息全局应用
     */

    private List securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN"new AuthorizationScope[]{new AuthorizationScope("global""")})))
                        .build()
        );
    }
以上配置成功后,在Swagger文档的页面中将会有Authorize按钮,只需要将请求头添加进去即可。如下图:

Swagger3.0 天天刷屏,真的香吗?

如何携带公共的请求参数?

不同的架构可能发请求的时候除了携带TOKEN,还会携带不同的参数,比如请求的平台,版本等等,这些每个请求都要携带的参数称之为公共参数。

那么如何在Swagger中定义公共的参数呢?比如在请求头中携带。

Docket中的方法globalRequestParameters()可以设置公共的请求参数,接收的参数是一个List,因此只需要构建一个RequestParameter集合即可,如下:

@Bean
public Docket frontApi() {
   //构建一个公共请求参数platform,放在在header
   RequestParameter parameter = new RequestParameterBuilder()
      //参数名称
      .name("platform")
      //描述
      .description("请求的平台")
      //放在header中
      .in(ParameterType.HEADER)
      //是否必传
      .required(true)
      .build();
      //构建一个请求参数集合
      List parameters = Collections.singletonList(parameter);
        return new Docket(DocumentationType.OAS_30)
                .....
                .build()
                .globalRequestParameters(parameters);
    }
以上配置完成,将会在每个接口中看到一个请求头,如下图:

Swagger3.0 天天刷屏,真的香吗?

粗略是一个BUG

作者在介绍自动配置类的时候提到了一嘴,现在来简单分析下。

OpenApiAutoConfiguration这个自动配置类中已经导入OpenApiDocumentationConfiguration这个配置类,如下一段代码:

@Import({
    OpenApiDocumentationConfiguration.class,
    ......
})
@EnableOpenApi的源码如下:

@Retention(value = java.lang.annotation.RetentionPolicy.RUNTIME)
@Target(value = {java.lang.annotation.ElementType.TYPE})
@Documented
@Import(OpenApiDocumentationConfiguration.class)
public @interface EnableOpenApi 
{
}
从源码可以看出:@EnableOpenApi这个注解的作用就是导入OpenApiDocumentationConfiguration这个配置类,纳尼???

既然已经在自动配置类OpenApiAutoConfiguration导入了,那么无论需不需要在配置类上标注@EnableOpenApi注解不都会开启Swagger支持吗?

「测试一下」:不在配置类上标注@EnableOpenApi这个注解,看看是否Swagger运行正常。结果在意料之中,还是能够正常运行。

「总结」:作者只是大致分析了下,这可能是个BUG亦或是后续有其他的目的,至于结果如此,不想验证了,没什么意思。

总结

这篇文章也是尝了个鲜,个人感觉不太香,有点失望。你喜欢吗?


本站声明: 本文章由作者或相关机构授权发布,目的在于传递更多信息,并不代表本站赞同其观点,本站亦不保证或承诺内容真实性等。需要转载请联系该专栏作者,如若文章内容侵犯您的权益,请及时联系本站删除。
换一批
延伸阅读

9月2日消息,不造车的华为或将催生出更大的独角兽公司,随着阿维塔和赛力斯的入局,华为引望愈发显得引人瞩目。

关键字: 阿维塔 塞力斯 华为

加利福尼亚州圣克拉拉县2024年8月30日 /美通社/ -- 数字化转型技术解决方案公司Trianz今天宣布,该公司与Amazon Web Services (AWS)签订了...

关键字: AWS AN BSP 数字化

伦敦2024年8月29日 /美通社/ -- 英国汽车技术公司SODA.Auto推出其旗舰产品SODA V,这是全球首款涵盖汽车工程师从创意到认证的所有需求的工具,可用于创建软件定义汽车。 SODA V工具的开发耗时1.5...

关键字: 汽车 人工智能 智能驱动 BSP

北京2024年8月28日 /美通社/ -- 越来越多用户希望企业业务能7×24不间断运行,同时企业却面临越来越多业务中断的风险,如企业系统复杂性的增加,频繁的功能更新和发布等。如何确保业务连续性,提升韧性,成...

关键字: 亚马逊 解密 控制平面 BSP

8月30日消息,据媒体报道,腾讯和网易近期正在缩减他们对日本游戏市场的投资。

关键字: 腾讯 编码器 CPU

8月28日消息,今天上午,2024中国国际大数据产业博览会开幕式在贵阳举行,华为董事、质量流程IT总裁陶景文发表了演讲。

关键字: 华为 12nm EDA 半导体

8月28日消息,在2024中国国际大数据产业博览会上,华为常务董事、华为云CEO张平安发表演讲称,数字世界的话语权最终是由生态的繁荣决定的。

关键字: 华为 12nm 手机 卫星通信

要点: 有效应对环境变化,经营业绩稳中有升 落实提质增效举措,毛利润率延续升势 战略布局成效显著,战新业务引领增长 以科技创新为引领,提升企业核心竞争力 坚持高质量发展策略,塑强核心竞争优势...

关键字: 通信 BSP 电信运营商 数字经济

北京2024年8月27日 /美通社/ -- 8月21日,由中央广播电视总台与中国电影电视技术学会联合牵头组建的NVI技术创新联盟在BIRTV2024超高清全产业链发展研讨会上宣布正式成立。 活动现场 NVI技术创新联...

关键字: VI 传输协议 音频 BSP

北京2024年8月27日 /美通社/ -- 在8月23日举办的2024年长三角生态绿色一体化发展示范区联合招商会上,软通动力信息技术(集团)股份有限公司(以下简称"软通动力")与长三角投资(上海)有限...

关键字: BSP 信息技术
关闭
关闭