自訂 OpenAPI 使用者介面

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

1. 自訂 CSS 檔案，以編輯 OpenAPI 使用者介面標頭列中的 HTML 元素樣式。
   這個 CSS 檔案會將下列格式需求視為有效。

   • CSS 檔案指定了至少一個以 .swagger-ui .headerbar 開頭的元素。
   • 只會使用在以 .swagger-ui .headerbar 開頭的 CSS 元素下指定的內容。
   • 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/openapi-3.1/customization.css 位置，以進行自動監視。 第一個 CSS 檔案的位置會套用至 /openapi/ui 端點。 第二個 CSS 檔案的位置會套用至 /api/explorer 端點。 如果您也想指定自訂標誌，請將它儲存在 $server.config.dir/mpopenapi/images/custom-logo.png 和 $server.config.dir/openapi-3.1/images/custom-logo.png 位置，並在這兩個位置中的 CSS 檔案內參照它。

   附註: 只會監視 CSS 檔案是否有更新項目。 不會監視標誌檔案。 對其中一個標誌檔案進行變更之後，必須接著更新至對應的 CSS 檔案，以便動態採用該變更。
3. 選用項目: 自訂作業檔案的控制檔監視。

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

   mp.openapi.extensions.liberty.file.polling.interval 配置內容指定檢查受監視檔案是否有更新的頻率。 這個內容的值是一個非負數的整數。 間隔的單位是秒。 預設值是 2 秒。 如果將值設為 0，則會停用檔案監視。

   配置是由 MicroProfile Config 規格來注入。

   附註: 只有在啟用 mpOpenAPI-1.0 或 openapi-3.1 特性時，才會檢查此內容的值。