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文檔，我夠了。
