自訂Swagger Request Header

前言

先前的文章曾經介紹過什麼是 Swagger 服務（請參考 透過Swagger自動產生 WebAPI規格文件）

現在也確實有越來越多服務都透過 Swagger 來建置 API 平台，但很多使用者實際運用的時候都會發現一個大問題

我要怎麼設定 Request Header？

沒錯，Swagger UI 原本預設並沒有能設定 Header 參數的地方

但實務上，網站常常需要透過 Header 夾帶資訊，例如 Token、語系....等

如果 Swagger 無法設定 Header 參數的話，只能說是一個虛有其表的噱頭罷了

目前狀況

其實只要透過幾個簡單的步驟，就能達到自訂 Header 參數的目的，以下我們來做個簡單的範例

我們延續先前文章的專案來示範，先看一下目前的 UI 介面是無法賦予 Header 的資訊

操作步驟

Step1. 首先必須新增一個類別，並實作 IOperationFilter 介面中的 Apply 方法

這裡我先來建立一個 HeaderFilter 的 class，內容如下：

程式碼中有一段在 operation.parameters 加入的 parameter 物件，其實就是我們指定的 Header 參數所要呈現的相關設定

包含參數名稱、位置、資料型態、描述以及是否必填...等屬性

若需要的 Header 參數為多個，就可依需求在這裡 Add 多筆 parameter（在此我們先以一個為例）

Step2. 在 SwaggerConfig.cs 檔案的 EnableSwagger 段落加入這段程式碼 "c.OperationFilter<HeaderFilter>()"

其中<>內的型別參數就是在 Step1 所建立的 class HeaderFilter

以上兩個步驟做完就可以運作了，沒錯，就是這麼簡單，我們先把專案 run 起來看看吧！

確實可以在 UI介面上看到有多出了一個 Authorization 欄位，資料型態、描述說明...等也都跟我們程式裡面的設定一樣

驗證

那我怎麼知道這個欄位的動作真的可以正常運作？接下來就實際送個 request 來測試看看吧

我們在這個欄位輸入測試的 Token "header.payload.signature"，並檢查瀏覽器的 Network

可以看到 Request Headers 出現了 authorization 的屬性，而且資料內容也沒錯

接下來在程式碼下個中斷點，看一下有沒有辦法拿到送出的資料內容

在程式碼裡面可以順利的拿到 Header.authorization 資料

驗證無誤，打完收工

結論

Swagger 若可以設定 Header 參數的話，在應用上才會比較貼近實際的狀況，相信也會提高開發人員及企業的使用意願

而且 Swagger UI 的介面真的非常友善，一個 API 的部署環境還能搭配漂亮的設計畫面

開發人員在程式碼內的規格或說明若有修改，swagger 就能即時更新，這樣的好東西不用嗎？？？