[18.0.0.1 以及更新版本]

自訂 OpenAPI 使用者介面

您可以自訂 /openapi/ui 端點中之可用 OpenAPI 使用者介面的各個層面。Liberty 會監視自訂作業 CSS 檔案的變更,以處理及更新 OpenAPI 使用者介面的變更。

開始之前

如果要瞭解如何建置和啟用 OpenAPI 說明文件,請參閱以 MicroProfile OpenAPI 1.0 產生 REST API 說明文件

程序

  1. 自訂 CSS 檔案,以編輯 OpenAPI 使用者介面標頭列中的 HTML 元素樣式。 這個 CSS 檔案會將下列格式需求視為有效。
    • CSS 檔案指定了至少一個以 .swagger-ui .headerbar 開頭的元素。
    • 只會使用 CSS 元素之下所指定以 .swagger-ui .headerbar 開頭的內容。
    • CSS 檔案所參照之自訂標誌檔案必須是 PNG 格式。
    • 自訂標誌檔案必須命名為 custom-logo.png,並且放在 images/custom-logo.png 中。
    • 標誌檔案路徑必須相對於 CSS 檔案。
    • CSS 檔案必須將 background-image 內容設為 url(images/custom-logo.png) 值,以參照標誌影像。

    下列 Snippet 說明如何置換 CSS 檔案:

    .swagger-ui .headerbar {
       background-color: #5f3345;
    }
     .swagger-ui .headerbar .headerbar-wrapper {
       background-image: url(images/custom-logo.png);
    }
  2. 針對您的自訂作業 CSS 檔案,配置檔案監視。

    您可以將自訂 CSS 檔案儲存在 $server.config.dir/mpopenapi/customization.css 位置,以進行自動監視。如果您也想指定自訂標誌,請將它儲存在 $server.config.dir/mpopenapi/images/custom-logo.png 位置,並在 CSS 檔案內參照它。

    註: 只會監視 CSS 檔案是否有更新。不會監視標誌檔案。對標誌檔案進行變更之後,必須接著更新至 CSS 檔案,以便動態套用該變更。
  3. 選擇性的: 控制自訂作業檔案的檔案監視。

    依預設,Liberty 會持續監視 CSS 自訂作業檔案。不過,監視檔案會使用額外的系統資源。您可以變更檢查受監視檔案是否有更新的頻率。如果您沒有任何自訂作業檔案,則最好關閉檔案監視。

    mp.openapi.extensions.liberty.file.polling.interval 配置內容指定檢查受監視檔案是否有更新的頻率。這個內容的值是一個非負數的整數。間隔的單位是秒。預設值是 2 秒。如果將值設為 0,則會停用檔案監視。
    配置是由「MicroProfile 配置」規格來注入。
    註: 只有在啟用 mpOpenAPI-1.0 特性時,才會檢查這個內容的值。

指示主題類型的圖示 作業主題

檔名:twlp_api_mpopenapi_custom.html