1. 背景
最近在准备新的Release时，在security check中收到了withesource的一个Ticket，说是用到的springfox-swagger-ui 2.9.2存在securit Vulnerability，给出的解决建议是升级到3.2版本以上，但是在maven repository上springfox-swagger-ui的最高版本才3.0.0，而且配置在github中的withesource plugin并没有发现这一问题，总之不太正常的样子。
不过呢，一直以来springfox-swagger-ui:2.9.2和springfox-swagger2:2.9.2这个版本将SpringBoot限制在了2.5.7,这个版本所包含的spring-core:5.3.13存在securit Vulnerability--CVE-2021-22060，目前处理方案是指定include spring-core:5.3.14以上版本.
而单方面升级spring-boot-starter到2.6.4或者升级springfox-swagger2 到最新的3.0.0，都会引发NPE从而导致启动失败,这恐怕也可以解释为何springfox-swagger2:2.9.2的下载使用量遥遥领先：
所以，1）为了应对这一潜在风险，2）解封SpringBoot升级, 我决定探索如何升级到Swagger3(实际上Swagger加入Apach基金会后就改名OpenAPI,成了一个标准了).
2.头晕流水账
本着糙快猛的想法，在网上搜了一圈，却发现讲SpringBoot集成Swagger2有非常多，这篇SpringBoot集成Swagger2就讲的不错；讲swagger3与swagger2区别比较少，但都比较简单， 比如这篇swagger3与swagger2的区别，作为摘要还是不错的，又或者是这篇A Visual Guide to What's New in Swagger 3.0，对于官方文档OAS3 -- OpenAPI 3.0和OAS2 -- Swagger 2.0总结的非常好，和官网博客A Guide to What’s New in OpenAPI 3.0 一样棒。
看完这么一圈文档和博客之后，我也动手做了一些代码的调整，但在关于How to set ApiToken in Request Header via "SwaggerDocumentationConfig" during using OpenAPI 3.0这个点上，一直没找到方法，其实就是Authentication and Authorization这一块。因为我们这边没有UserInfo，这个Release是作为一个Component来为多个Project提供数据的，因而会有同时支持不同的权限验证方式的需求，比如最简单的 -- 配置文件中ApiToken，和常规一些的 -- 第三方Keycloak验证。
当前在UI上的效果如下图所示
而按照Swagger Editor Live Demo(OpenAPI 3.0)给出的效果是这样的：
这其中的Gap存在于几个方面:
<1> 在Swagger Editor 中编写JSON或者YAML时，在每个URL Path上都要单独写security的配置，转化到代码里就更繁琐了；这也就意味着如果我如果要在Header中多加一个参数，就是在所有接口定义上写一遍，这也是为什么我在Swagger 2.0中就使用ParameterBuilder和globalOperationParameters在SwaggerDocumentationConfiguration进行全局配置，奈何在OpenAPI 3.0中它们都没了。
<2> 如果通过OpenAPI 3.0中的securitySchemes在SwaggerDocumentationConfiguration中全局配置api_key的话，官网demo中给出了Server端拿出UserInfo来验证的示例，我不确定之前采用的那种在OncePerRequestFilter进行拦截处理的方式是否可行
<3> 还有就是当前采用配置WebSecurityConfigurerAdapter来集成jwt Authorization，也不确定更新后能否适用
3. SwaggerDocumentationConfiguration里见真章
最后最后最后还是在代码里找到了答案，查看ParameterBuilder发现它引用的路径是springfox.documentation.builders.ParameterBuilder
,然后根据这个路径去对应的springfox-swagger2 3.0.0中的相同位置寻找,果然有所发现，猜测RequestParameterBuilder就是用来替换ParameterBuilder的，一番代码改动居然OK:
然后使用globalRequestParameters而不是globalOperationParameters进行全局配置，再加上在其他地方做的必要代码改动，最后居然运行成功，并且效果也符合预期，证明确实是用来替换的！
把我最后的的SwaggerDocumentationConfiguration Using OAS_30代码贴一下, 其中注释部分贴出了对应Using Swagger 2.0的对比:
package io.swagger.configuration;
import io.swagger.annotations.ApiOperation;
import io.swagger.v3.oas.annotations.Operation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ApiInfoBuilder;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import java.util.ArrayList;
import java.util.List;
@javax.annotation.Generated(value = "io.swagger.codegen.v3.generators.java.SpringCodegen", date = "2022-02-23T08:01:35.894Z[GMT]")
@Configuration
public class SwaggerDocumentationConfig {
@Bean
public Docket customImplementation(){
// Swagger 2.0
// ParameterBuilder aParameterBuilder = new ParameterBuilder();
// aParameterBuilder
// .parameterType("header")
// .name("ApiToken")
// .description("")
// .modelRef(new ModelRef("string"))
// .required(false).build();
// List<Parameter> parameters = new ArrayList<Parameter>();
// parameters.add(aParameterBuilder.build());
// ParameterBuilder bParameterBuilder = new ParameterBuilder();
// bParameterBuilder
// .parameterType("header")
// .name("Authorization")
// .defaultValue("Bearer ")
// .description("The value should be in format of 'Bearer ${access_token}' ")
// .modelRef(new ModelRef("string"))
// .required(false).build();
// parameters.add(bParameterBuilder.build());
// OAS 3.0
RequestParameterBuilder requestParameterBuilder = new RequestParameterBuilder();
RequestParameter aRequestParameter = requestParameterBuilder
.in(ParameterType.HEADER)
.name("ApiToken")
.description("")
.required(false)
.build();
RequestParameter bRequestParameter = requestParameterBuilder
.in(ParameterType.HEADER)
.name("Authorization")
.description("The value should be in format of 'Bearer ${access_token}' ")
.required(false)
.build();
List<RequestParameter> requestParameters = new ArrayList<>();
requestParameters.add(aRequestParameter);
requestParameters.add(bRequestParameter);
return new Docket(DocumentationType.OAS_30) // DocumentationType.SWAGGER_2
.select()
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) Swagger 2.0
.apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) // OAS 3.0
.build()
.directModelSubstitute(org.threeten.bp.LocalDate.class, java.sql.Date.class)
.directModelSubstitute(org.threeten.bp.OffsetDateTime.class, java.util.Date.class)
// .globalOperationParameters(parameters); // Swagger 2.0
.globalRequestParameters(requestParameters)
.apiInfo(apiInfo());
}
ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger Petstore")
.description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.termsOfServiceUrl("")
.version("1.0.0")
.contact(new Contact("","", "apiteam@swagger.io"))
.build();
}
// New for OAS 3.0
@Bean
public OpenAPI openApi() {
return new OpenAPI()
.info(new Info()
.title("Swagger Petstore")
.description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
.termsOfService("")
.version("1.0.0")
.license(new License()
.name("Apache 2.0")
.url("http://www.apache.org/licenses/LICENSE-2.0.html"))
.contact(new io.swagger.v3.oas.models.info.Contact()
.email("apiteam@swagger.io")));
}
}
4. SpringFox Boot Starter 3.0.0
当然，上面仅仅是针对我的痛点贴出了我所需要的SwaggerDocumentationConfiguration的代码，SpringBoot集成OpenAPI 3.0还有其他的代码需要添加修改，号称全家桶的SpringBoot其实已经针对OpenAPI 3.0推出了springfox-boot-starter 3.0.0，目前有且仅有这一个版本，它是包含有springfox-core:3.0.0的。
然后它有一个完整的Springfox Reference Documentation，对Gradle、Maven、Spring Boot Applications、Regular spring mvc都分别做了讲解，在Quick start guides这个章节中更是用示例代码做了详细的说明，只不过都没有提到上面我想要的。
简单贴一个摘要，正好说明前面提到的swagger3与swagger2区别整理的不错
5. springdoc-openapi-ui
在查找各种思路时，还发现了一个同样支持OAS 3.0的包：springdoc-openapi-ui，描述为Library for OpenAPI 3 with spring-boot By Badr NASS LAHSEN, 有兴趣的话可以去看看springdoc文档，我够了。
