踩坑前言
Swagger3.0出來一段時間了，雖然簡化了基礎的配置，但作為一個大版本的更新肯定存在不少問題，不少2.x版本的類都被标記為過時了，大部分類的構造與屬性設定依舊都交給了對應的Buidler處理，但不少配置上都引入了函數式接口去處理，對于對函數式程式設計不太了解的開發者而言可能有一定的配置難度。目前國内較少對3.0版本的配置介紹，是以自己在項目裡将Swagger更新到3.0後看了下替代了标記過時(@Deprecated)相應功能的源碼進行相應的配置，結果踩了2個坑，是以分享下踩坑記錄與3.0的通用配置方式。
踩坑記錄
項目中使用了jwt鑒權，但無論對于開發人員還是測試人員來說每次Swagger測接口前都要登入擷取token，每次傳token都是一件很麻煩的事，是以我便打算按Swagger比較常用的全局參數設定将Authorization設為全局header并設定預設值，于是有了以下3.0(OAS_30指Open API Spefication 3.0)中的配置：
以上配置中的query()可以看成是Swagger3.0中配置風格的一個核心：在配置類中建立好相應的屬性對象builder，并暴露一個該builder的Conumser函數式接口作為參數的方法，開發者根據需要提供一個Consumer進行對該builder的操作(屬性設定)，隻要了解了該風格相信基本上新版本的配置看看源碼也能很快上手。
以上配置代碼query()方法中我取了RequestParameterBuilder類中的屬性對象simpleParameterBuilder引用進行了屬性設定，RequestParameterBuilder部分源碼：
其實個人認為既然內建SpringBoot了以properties類為主導進行屬性設定而非Builder與FunctionalInterface對開發者使用而言會更便利，現在先踩坑填坑。按照對2.x的版本配置與了解個人以為以上的配置應該是沒有問題的，然而居然出現了2個坑。
當我添加一個Authorization的全局header的時候測試時發現怎麼傳都沒有傳到後端，一開始以為是Swagger的bug，但考慮到這個name的敏感性，我就去翻了下OpenAPI 3.0(Swagger 3.0是按照OpenAPI 3.0的規範去設計實作的,文檔的資料格式也是遵循3.0規範)，于是翻出了以下内容：
當全局header參數中包含命名為Accpet、Content-Type、Authorization的參數時，參數的定義将被忽略。于是我加了一個非忽略header，得到了以下結果：
可以看到全局header設定中debug是能接收到的，而Authorization是被忽略的，即基本确認非bug，隻是我沒有看規範而已。既然以該方式定義的Authorization header無法被接收，但Swagger以往的版本還有一種設定全局token的方式-SecurityContext與SecurityReference：
SecurityContext與SecurityReference的設定與以往版本變化不大，結果也達到了個人的期望(後端能擷取到Authorization header)，隻是該方式配置的header無法設定預設值而已，效果圖如下：
雖然通過query()方法設定了參數預設值，但實質上Swagger并沒有把該預設值設定到頁面上，從坑1中的示範圖1可以看到全局參數即使設定了初始值1，但頁面上還是空的。該坑确認了是3.0的bug，在github裡也找到了相應的issue，該bug已加到了3.0.1的裡程碑中(即3.0.1版本會修複)：
結語
雖然官方架構的使用更具有普遍性，但目前還是覺得自己寫的香，如果以上3.0版本出現的問題會影響目前項目的測試使用則不建議先更新，玩玩尚可。