了解官方Swagger Starter后再回顾Spring Boot

川长思鸟来 2022-12-13 04:02 127阅读 0赞

> springfox终于给Swagger做了个Spring Boot Starter了，看来我自己写的[swagger starter][]可以在不久后可以退役了。

# 为什么之前官方不出相应的Spring Boot Starter #

刚开始接触到Spring Boot时，很疑惑为什么Swgger作为一款流行的文档框架却没有自己的Spring Boot Starter。后来为了自己的方便，手撸了一套给自己用的starter，当时也因此了解了Spring Boot是如何进行自动化配置的，配置文件里的配置提示是读取哪个文件的。在撸starter的过程也发现，Swagger中的对象创建基本都是使用Builder构造器模式的，如通过`ApiInfoBuilder`创建`ApiInfo`:

public class ApiInfoBuilder {
       ......
      public ApiInfo build() {
        return new ApiInfo(title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions);
      }
    }

而`ApiInfo`类中是没有setter的，属性都是通过构造函数设置的:

public class ApiInfo {
      ......
      
      public ApiInfo(......) {
        ......
      }
      
      ......
    }

众所周知，Java属性的通用设置方式有2种：构造方法、setter方法。像Spring Boot这种如此通用的框架肯定会使用最通用的方式以获得最广泛的框架兼容：通过配置文件的属性名找到相应的setter方法并进行属性注入。而Swagger这种以Builder模式设置属性自然无法兼容，因为Spring Boot读取了配置属性也找不到相应的setter方法，如果swagger要想Spring Boot兼容，主要有以下2种方式：

1.  官方方式：将Builder模式设置属性改为setter
2.  非官方方式：创建新的属性配置类再创建Bean到容器中，像个人比较久之前写的[swagger starter][]就是以这种方式，如：

@Setter
    @ToString
    public class ApiInfoProperties {
    
        private String version;
        private String title;
        private String description;
        private String termsOfServiceUrl;
        private String license;
        private String licenseUrl;
        private ContactProperties contact = new ContactProperties();
    
        ApiInfo toApiInfo() {
            return new ApiInfo(title, description, version, termsOfServiceUrl, contact.toContact(), license, licenseUrl, Collections.emptyList());
        }
    }

目前官方的Swagger Starter只支持了基础功能的属性配置， 像一些路径过滤(path-selector)、全局参数/header(global-parameters)、安全校验(security-schema、security-contexts)的自动化配置还没做，不过springfox选择兼容Spring Boot的方式如无意外都会是官方方式，即将Builder改为setter，以下是目前官方starter的一个配置类摘要：

@ConfigurationProperties("springfox.documentation")
    public class SpringfoxConfigurationProperties {
      private boolean autoStartup = true;
      private boolean enabled = true;
      @NestedConfigurationProperty
      private SwaggerConfigurationProperties swagger;
      @NestedConfigurationProperty
      private OpenApiConfigurationProperties openApi;
      @NestedConfigurationProperty
      private SwaggerUiConfigurationProperties swaggerUi;
    
      public boolean isAutoStartup() {
        return autoStartup;
      }
    
      public void setAutoStartup(boolean autoStartup) {
        this.autoStartup = autoStartup;
      }
      
      ......
    }

# Swagger 3.0进行了哪些改进 #

具体改进点可以在[官文文档][Link 1]查看，个人就简单列几个个人认为比较重要的：

*  支持webflux，之前有项目使用webflux的就有点郁闷Swagger不支持，要支持的话也只能靠Swagger 3.0的SNAPSHOT实属麻烦，最后还是用回postman
 *  移除了第三方的依赖库，如guava，之前版本的这些依赖库个人也是认为比较让人诟病的，因为这些依赖库基本大部分项目里都会有导致重复
 *  添加了`springfox-boot-starter`，可支持传统web与响应式webflux，目前只提供了简单的功能
 *  移除了`@EnableSwagger2`注解，简化了配置，更改了文档地址，目前只需引入starter依赖运行项目即可访问`http://host:port/{context-path}/swagger-ui/`查看接口文档

# 快速开始 #

## 添加依赖 ##

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

## 启动项目访问Swagger地址 ##

![6d436c2e488545682eb8d3dca528de96.png][]

以上是一个无配置的官方swagger starter demo，但其实有配置界面也差不多，因为starter目前还不支持`ApiInfo`、`SecurityContext`之类的配置，更多的项目配置例子(如webflux)可参考文末官方例子。swagger starter的配置都是以`springfox.documentation`为前缀的，具体的就不说了，可以直接在配置文件中看提示文档。

# 参考资源 #

官方文档：[https://github.com/springfox/springfox][Link 1]  
官方例子：[https://github.com/springfox/springfox-demos][https_github.com_springfox_springfox-demos]

[swagger starter]: https://blog.csdn.net/z28126308/article/details/84187221
[Link 1]: https://github.com/springfox/springfox
[6d436c2e488545682eb8d3dca528de96.png]: /images/20221123/2fe79efe77f74a83b4db0e0a561527de.png
[https_github.com_springfox_springfox-demos]: https://github.com/springfox/springfox-demos