Swagger UI Header Parameters

Swagger UI 是由 Swagger 官方維護的一套純由 HTML / CSS / Javascript 打造的 Swagger 工具。 Demo

Swagger UI 不需要安裝任何套件就可以在瀏覽器上運作，不過有些 API 設計上會需要 API key ，所以 Swagger UI 也很貼心地提供， API key 在右上角提供 API key 的輸入框供人使用，只是這 API key 是用 GET parameter 的方式附加在 API 的 path 之後。

例如 /user/login 這個 API 在填上 Swagger UI 右上角的 API key 情況下，發出 request 時就會變成 /user/login?api_key=your_api_key 。

但這時如果要改成將 API key 放在 HTTP header 時就需要改些程式了(本篇以 Swagger UI 2.1.4 作為範例)。

只要打開 dist/index.html ，搜尋 #input_apiKey ，然後進行修改，例如：

原本：

function addApiKeyAuthorization(){
    var key = encodeURIComponent($('#input_apiKey')[0].value);
    if(key && key.trim() != "") {
        var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
        window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
        log("added key " + key);
    }
}

修改後版本：

$('#input_apiKey').change(function() {
  var key = $('#input_apiKey')[0].value;
  if(key && key.trim() != "") {
    window.swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("Authorization", key, "header"));
  }
})

上述的 Authorization 可以替換成任何你想要的 HTTP Header 。

詳細一些客製化的方法，可以詳閱 Swagger UI 的 GitHub ！

swagger